refactor(node/validator): simplify and de-verbose the validator module (leanEthereum#1108)

Clarity and documentation pass over the validator service, registry, and
constants. No behavior change; the unit tests pass.

- Docs: collapse verbose module/class/method docstrings to one line where
  the signature already says it, strip the banned Why:/Effect: labels from
  the constants, and trim step-narration comments and debug logs. Keep the
  genuine rationale (authenticated network-tip bound, wait-for-block, the
  local-processing threshold, the gated-slot invariant) glued to its code.
- Modern Python: use dataclasses.replace to carry the unchanged signing key;
  resolve the proposer by direct registry membership instead of a loop that
  recomputed it; name the attestation dedup horizon as a constant.
- Inline the single-use helpers (node-mapping load, secret-key load, the
  attestation signer) so each flow reads in one place.

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

Author: tcoratger

src/lean_spec/node/validator/__init__.py

@@ -1,18 +1,9 @@
 """
-Validator service module for producing blocks and attestations.
+Validator key management and duty execution.
 
 Validators are the active participants in Ethereum consensus.
-This module provides:
-
-- A registry that manages validator secret keys for signing
-- A service that drives duty execution based on the slot clock
-
-Lifecycle:
-
-1. Load validator keys from YAML configuration
-2. Start the service to monitor slot intervals
-3. At interval 0, produce blocks if scheduled
-4. At interval 1, produce attestations for non-proposers
+A registry holds the signing keys this node controls.
+A service runs each validator's duties off the slot clock.
 """
 
 from lean_spec.node.validator.registry import ValidatorRegistry

src/lean_spec/node/validator/constants.py

@@ -1,44 +1,12 @@
-"""
-Validator duty-gate thresholds.
-
-Informative, not normative:
-
-- Shape when this node signs.
-- Do not change what consensus accepts.
-- Clients may diverge without breaking interop.
-"""
+"""Validator duty-gate thresholds"""
 
 from typing import Final
 
 SYNC_LAG_THRESHOLD: Final[int] = 4
-"""Slot lag past which the local view is too stale to sign.
-
-Why:
-    We justify and finalize within a handful of slots.
-    A 4-slot lag is one full justification window behind real time.
-    A vote from that view lands on a subtree the network has left.
-"""
+"""Slot lag past which the local view is too stale to sign."""
 
 NETWORK_STALL_THRESHOLD: Final[int] = 8
-"""Slot lag past which the whole network is treated as stalled.
-
-Why:
-    Set to twice the local threshold (8 = 2 * 4).
-    Ordinary jitter at the local boundary must not trip this branch.
-
-Effect:
-    Even the freshest locally validated block is 8 slots behind.
-    The cause is a streak of skipped proposals, not this node lagging.
-    Duties stay live so the chain can advance through the gap.
-"""
+"""Slot lag treated as a network-wide stall, so duties stay live (twice the local gate)."""
 
 HYSTERESIS_BAND: Final[int] = 2
-"""Slot band that holds the gate closed near the threshold.
-
-Why:
-    Without a band a single late gossip block flips the decision.
-    Slot-over-slot flips would stutter the attestation stream.
-
-Effect:
-    Once closed, the gate reopens only when lag drops to 4 - 2 = 2.
-"""
+"""Slot band holding the gate closed near the threshold, so it cannot flip slot-to-slot."""

src/lean_spec/node/validator/registry.py

@@ -1,27 +1,25 @@
 """
-Validator registry for managing validator keys.
+Validator key loading.
 
-Loads validator keys from YAML configuration files compatible with ream and zeam.
+Two YAML files describe the keys.
 
-The registry supports two YAML files:
+- validators.yaml maps each node to the validator indices it controls:
 
-1. **validators.yaml** - Maps node IDs to validator indices:
+    lean_spec_0:
+    - 0
+    - 1
+    lean_spec_1:
+    - 2
 
-       lean_spec_0:
-       - 0
-       - 1
-       lean_spec_1:
-       - 2
+- validator-keys-manifest.yaml lists each validator's key metadata and file paths:
 
-2. **validator-keys-manifest.yaml** - Contains key metadata and file paths:
-
-       key_scheme: SIGTopLevelTargetSumLifetime32Dim64Base8
-       hash_function: Poseidon
-       num_validators: 3
-       validators:
-       - index: 0
-         public_key_hex: 0xe2a03c...
-         private_key_file: validator_0_secret_key.ssz
+    key_scheme: SIGTopLevelTargetSumLifetime32Dim64Base8
+    hash_function: Poseidon
+    num_validators: 3
+    validators:
+    - index: 0
+      public_key_hex: 0xe2a03c...
+      private_key_file: validator_0_secret_key.ssz
 """
 
 from __future__ import annotations
@@ -39,9 +37,6 @@
 
 logger = logging.getLogger(__name__)
 
-type NodeValidatorMapping = dict[str, list[int]]
-"""Mapping from node identifier to list of validator indices."""
-
 
 class ValidatorManifestEntry(BaseModel):
     """Single validator entry from the manifest file."""
@@ -63,12 +58,7 @@ class ValidatorManifestEntry(BaseModel):
 
 
 class ValidatorManifest(BaseModel):
-    """
-    Key metadata from validator-keys-manifest.yaml.
-
-    Contains cryptographic scheme info and validator key paths.
-    This format matches ream's manifest structure.
-    """
+    """Key metadata for every validator, matching the ream manifest format."""
 
     key_scheme: str
     """Signature scheme identifier (e.g., SIGTopLevelTargetSumLifetime32Dim64Base8)."""
@@ -96,46 +86,18 @@ class ValidatorManifest(BaseModel):
 
     @classmethod
     def from_yaml_file(cls, path: Path) -> ValidatorManifest:
-        """
-        Load manifest from YAML file.
-
-        Args:
-            path: Path to validator-keys-manifest.yaml.
-
-        Returns:
-            Validated ValidatorManifest instance.
-        """
+        """Load and validate a manifest from a YAML file."""
         with path.open() as f:
             return cls.model_validate(yaml.safe_load(f))
 
 
-def load_node_validator_mapping(path: Path) -> NodeValidatorMapping:
-    """
-    Load node-to-validator index mapping from validators.yaml.
-
-    Maps node identifiers to lists of validator indices they control.
-
-    Args:
-        path: Path to validators.yaml.
-
-    Returns:
-        Mapping from node ID to list of validator indices.
-        Empty dict if file is empty.
-    """
-    with path.open() as yaml_file:
-        parsed_yaml = yaml.safe_load(yaml_file)
-    # YAML returns None for empty file
-    return parsed_yaml or {}
-
-
 @dataclass(frozen=True, slots=True)
 class ValidatorEntry:
     """
     A single validator's key material.
 
-    Holds the index and both secret keys needed for signing.
-    Attestation and proposal keys are separate to allow independent
-    OTS signing within the same slot.
+    Attestation and proposal keys are separate.
+    This lets one validator sign both within the same slot without OTS conflict.
     """
 
     index: ValidatorIndex
@@ -150,63 +112,33 @@ class ValidatorEntry:
 
 @dataclass(slots=True)
 class ValidatorRegistry:
-    """
-    Registry of validator keys controlled by this node.
-
-    The registry holds secret keys for validators assigned to this node.
-    It provides lookup by validator index for signing operations.
-    """
+    """Signing keys for the validators this node controls."""
 
     _validators: dict[ValidatorIndex, ValidatorEntry] = field(default_factory=dict)
     """Map from validator index to entry."""
 
     def add(self, entry: ValidatorEntry) -> None:
-        """
-        Add or replace a validator entry in the registry.
-
-        Replaces any existing entry with the same index.
-        Used to persist updated key state after signing.
-
-        Args:
-            entry: Validator entry to add.
-        """
+        """Add a validator entry, replacing any existing entry with the same index."""
         self._validators[entry.index] = entry
 
     def get(self, index: ValidatorIndex) -> ValidatorEntry | None:
-        """
-        Get validator entry by index.
-
-        Args:
-            index: Validator index to look up.
-
-        Returns:
-            Validator entry if found, None otherwise.
-        """
+        """Return the validator entry for an index, or None if not controlled."""
         return self._validators.get(index)
 
     def __contains__(self, index: ValidatorIndex) -> bool:
         """Check if we control this validator."""
         return index in self._validators
 
     def indices(self) -> ValidatorIndices:
-        """
-        Get all validator indices we control.
-
-        Returns:
-            ValidatorIndices collection.
-        """
+        """Return every validator index this node controls."""
         return ValidatorIndices(data=list(self._validators.keys()))
 
     def primary_index(self) -> ValidatorIndex | None:
         """
-        Get the primary validator index for store-level identity.
+        The store-level identity for this node, or None if it controls no validators.
 
-        Returns the first validator index in the registry.
-        With ATTESTATION_COMMITTEE_COUNT = 1, all validators share subnet 0,
-        so a single ID suffices for store-level operations.
-
-        Returns:
-            First validator index, or None if registry is empty.
+        Every validator shares the single attestation subnet.
+        So the first controlled index suffices for store-level operations.
         """
         if not self._validators:
             return None
@@ -219,24 +151,13 @@ def __len__(self) -> int:
     @classmethod
     def from_keys_directory(cls, node_id: str, base_directory: Path | str) -> ValidatorRegistry:
         """
-        Load a validator registry from the ream/zeam keystore layout.
-
-        Two files relative to the base directory:
-
-        - validators.yaml: maps each node to its validator indices.
-        - hash-sig-keys/validator-keys-manifest.yaml: lists each validator's
-          key metadata and SSZ file path.
+        Load a registry from the ream/zeam keystore layout.
 
-        Args:
-            node_id: Identifier looked up in the node-to-validator mapping.
-            base_directory: Directory containing the two layout files.
+        Reads validators.yaml and hash-sig-keys/validator-keys-manifest.yaml,
+        both relative to the base directory.
 
-        Returns:
-            Registry populated with the keys assigned to the node.
-
-        Raises:
-            FileNotFoundError: If the manifest file is missing.
-                A missing validators mapping is allowed and yields an empty registry.
+        A missing manifest raises FileNotFoundError.
+        A missing validators mapping is allowed and yields an empty registry.
         """
         base = Path(base_directory)
         manifest_path = base / "hash-sig-keys" / "validator-keys-manifest.yaml"
@@ -255,28 +176,13 @@ def from_yaml(
         validators_path: Path | str,
         manifest_path: Path | str,
     ) -> ValidatorRegistry:
-        """
-        Load validator registry from YAML configuration files.
-
-        Loading process:
-
-        1. Read validators.yaml to find indices assigned to this node
-        2. Read manifest to get key file paths
-        3. Load secret keys from SSZ files
-
-        Args:
-            node_id: Identifier for this node in validators.yaml.
-            validators_path: Path to validators.yaml.
-            manifest_path: Path to validator-keys-manifest.yaml.
-
-        Returns:
-            Registry populated with validator keys for this node.
-        """
+        """Load a registry for one node from its validators.yaml and manifest files."""
         validators_path = Path(validators_path)
         manifest_path = Path(manifest_path)
 
-        # Load node-to-validator mapping.
-        node_mapping = load_node_validator_mapping(validators_path)
+        # Read the node-to-validator mapping; an empty file parses to None.
+        with validators_path.open() as validators_file:
+            node_mapping = yaml.safe_load(validators_file) or {}
 
         # Get indices assigned to this node.
         assigned_indices = node_mapping.get(node_id, [])
@@ -308,7 +214,7 @@ def from_yaml(
                 )
                 continue
 
-            # Load attestation secret key from SSZ file.
+            # Decode the attestation key from its SSZ file.
             attestation_key_path = manifest_directory / manifest_entry.attestation_private_key_file
             try:
                 attestation_secret_key = SecretKey.decode_bytes(attestation_key_path.read_bytes())
@@ -321,7 +227,7 @@ def from_yaml(
                     f"Failed to load attestation key for validator {validator_index}: {exception}"
                 ) from exception
 
-            # Load proposal secret key from SSZ file.
+            # Decode the proposal key from its SSZ file.
             proposal_key_path = manifest_directory / manifest_entry.proposal_private_key_file
             try:
                 proposal_secret_key = SecretKey.decode_bytes(proposal_key_path.read_bytes())