fix(lstar): reject malformed justification state with typed errors (leanEthereum#1178)

Several partial functions enforced their preconditions by crashing with
an untyped exception instead of rejecting cleanly. In the honest block
flow the preconditions hold, but these functions are reachable on a state
reconstructed from untrusted bytes over sync or the database, where the
crash type differs per transliterating language.

This is robustness hardening, not a consensus change: every rejection
path already funnels to dropping the block, so an assertion error, a
value error, and a typed rejection are consensus-equivalent. The value
is a defined, language-neutral rejection in place of an incidental crash.

Changes:

- Slot justifiability is now total. A slot before the finalized boundary
  returns False instead of asserting; the equal-slot case still returns
  True through the immediate-justification window.

- Attestation processing validates the justification bookkeeping before
  unpacking the flat vote list into per-root segments. It rejects an
  empty registry, a vote list whose length is not the tracked-root count
  times the validator count, and a zero hash among the tracked roots.
  Two typed rejection reasons are added for the latter two.

Vectors:

- Justifiability gains two cases below the finalized boundary, which the
  previous assert could not produce.
- Two state-transition rejection vectors craft a decoded state that
  violates the length invariant and one that carries a zero-hash root.

Closes leanEthereum#1174

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

Author: tcoratger

src/lean_spec/spec/forks/lstar/errors.py

@@ -89,6 +89,12 @@ class RejectionReason(StrEnum):
     JUSTIFIED_SLOT_OUT_OF_RANGE = "JUSTIFIED_SLOT_OUT_OF_RANGE"
     """A justification query named a slot beyond the tracked justification window."""
 
+    ZERO_HASH_JUSTIFICATION_ROOT = "ZERO_HASH_JUSTIFICATION_ROOT"
+    """A tracked justification root is the zero hash, which is not a valid root."""
+
+    JUSTIFICATION_VOTES_LENGTH_MISMATCH = "JUSTIFICATION_VOTES_LENGTH_MISMATCH"
+    """The flat vote list length is not the tracked-root count times the validator count."""
+
     # Cryptographic verification
     INVALID_SIGNATURE = "INVALID_SIGNATURE"
     """An attestation signature or aggregate proof fails cryptographic verification."""

src/lean_spec/spec/forks/lstar/slot.py

@@ -41,13 +41,12 @@ def is_justifiable_after(self, finalized_slot: Slot) -> bool:
             finalized_slot: The last slot that was finalized.
 
         Returns:
-            True if the slot is justifiable, False otherwise.
-
-        Raises:
-            AssertionError: If this slot is earlier than the finalized slot.
+            True if the slot is a justification candidate.
+            False otherwise, including any slot before the finalized slot.
         """
-        # Ensure the candidate slot is not before the finalized slot.
-        assert self >= finalized_slot, "Candidate slot must not be before finalized slot"
+        # A slot before the finalized boundary is already settled, never a future candidate.
+        if self < finalized_slot:
+            return False
 
         # Calculate the distance in slots from the last finalized slot.
         # Convert to int for pure arithmetic operations below.

src/lean_spec/spec/forks/lstar/state_transition.py

@@ -197,8 +197,15 @@ def process_attestations(
         Raises:
             SpecRejectionError: TOO_MANY_ATTESTATION_DATA if the distinct data
                 count exceeds the per-block cap.
-            SpecRejectionError: EMPTY_AGGREGATION_BITS if an attestation that passes
-                the vote filters has no set bits.
+            SpecRejectionError: EMPTY_VALIDATOR_REGISTRY if the state holds no
+                validators to segment the vote tracking against.
+            SpecRejectionError: JUSTIFICATION_VOTES_LENGTH_MISMATCH if the flat
+                vote list length is not the tracked-root count times the
+                validator count.
+            SpecRejectionError: ZERO_HASH_JUSTIFICATION_ROOT if a tracked
+                justification root is the zero hash.
+            SpecRejectionError: EMPTY_AGGREGATION_BITS if an attestation that
+                passes the vote filters has no set bits.
             SpecRejectionError: VALIDATOR_INDEX_OUT_OF_RANGE if a set bit points
                 outside the validator registry.
         """
@@ -222,10 +229,33 @@ def process_attestations(
         #     votes:  [<--N-->][<--N-->] ...
         #
         # Slicing per segment recovers a vote list per root.
-        assert not any(root == ZERO_HASH for root in state.justifications_roots), (
-            "zero hash is not allowed in justifications roots"
-        )
         validator_count = len(state.validators)
+
+        # An empty registry leaves no segment width, so the flat layout cannot be recovered.
+        # The header stage already guards this, but the unpack below relies on it directly.
+        if validator_count == 0:
+            raise SpecRejectionError(
+                RejectionReason.EMPTY_VALIDATOR_REGISTRY,
+                "State holds no validators to segment justification votes against",
+            )
+
+        # The flat vote list must hold exactly one full validator segment per tracked root.
+        # A mismatched length means the segments no longer line up with the roots.
+        expected_vote_count = len(state.justifications_roots) * validator_count
+        if len(state.justifications_validators) != expected_vote_count:
+            raise SpecRejectionError(
+                RejectionReason.JUSTIFICATION_VOTES_LENGTH_MISMATCH,
+                "Justification vote list length does not equal tracked-root count times "
+                "validator count",
+            )
+
+        # The zero hash marks a skipped slot, never a real block, so it cannot track votes.
+        if any(root == ZERO_HASH for root in state.justifications_roots):
+            raise SpecRejectionError(
+                RejectionReason.ZERO_HASH_JUSTIFICATION_ROOT,
+                "Tracked justification roots contain the zero hash",
+            )
+
         justifications = {
             root: list(validator_votes)
             for root, validator_votes in zip(

tests/consensus/lstar/state_transition/test_justifiability.py

@@ -707,3 +707,49 @@ def test_nonzero_finalized_delta_12(
     - the candidate is justifiable.
     """
     justifiability_test(slot=512, finalized_slot=500)
+
+
+def test_slot_one_before_finalized_not_justifiable(
+    justifiability_test: JustifiabilityTestFiller,
+) -> None:
+    """
+    A slot one before the finalized slot is not justifiable.
+
+    Given
+    -----
+    - the finalized slot is 10.
+    - the candidate slot is 9.
+    - the delta is -1, before the finalized boundary.
+
+    When
+    ----
+    - the candidate is checked for justifiability.
+
+    Then
+    ----
+    - the candidate is not justifiable.
+    """
+    justifiability_test(slot=9, finalized_slot=10)
+
+
+def test_slot_far_before_finalized_not_justifiable(
+    justifiability_test: JustifiabilityTestFiller,
+) -> None:
+    """
+    A slot far before the finalized slot is not justifiable.
+
+    Given
+    -----
+    - the finalized slot is 100.
+    - the candidate slot is 90.
+    - the delta is -10, well before the finalized boundary.
+
+    When
+    ----
+    - the candidate is checked for justifiability.
+
+    Then
+    ----
+    - the candidate is not justifiable.
+    """
+    justifiability_test(slot=90, finalized_slot=100)

tests/consensus/lstar/state_transition/test_justification_votes_length_mismatch.py

@@ -0,0 +1,63 @@
+"""State Transition: justification vote-list layout guard"""
+
+import pytest
+
+from consensus_testing import (
+    BlockSpec,
+    ExpectedRejection,
+    StateTransitionTestFiller,
+    build_genesis_state,
+)
+from lean_spec.spec.forks import RejectionReason, Slot
+from lean_spec.spec.forks.lstar.containers import JustificationRoots, JustificationValidators
+from lean_spec.spec.ssz import Boolean, Bytes32
+
+pytestmark = pytest.mark.valid_until("Lstar")
+
+
+def test_vote_list_length_not_root_count_times_validators_rejects_block(
+    state_transition_test: StateTransitionTestFiller,
+) -> None:
+    """
+    A flat vote list whose length is not the tracked-root count times the validators rejects.
+
+    Given
+    -----
+    - 4 validators.
+    - the tracked justification roots hold one non-zero root.
+    - a full layout needs 4 bits (1 root times 4 validators).
+    - the flat vote list holds only 2 bits.
+    - the vote list length does not match the required layout.
+
+    When
+    ----
+    - a block at slot 1 is processed.
+
+    Then
+    ----
+    - the flat vote list cannot be segmented into full validator rounds.
+    - the block is rejected with JUSTIFICATION_VOTES_LENGTH_MISMATCH.
+    - the message states the vote list length does not equal the tracked-root count times the
+      validator count.
+    """
+    state_transition_test(
+        pre=build_genesis_state(num_validators=4).model_copy(
+            update={
+                "justifications_roots": JustificationRoots(data=[Bytes32(b"\x11" * 32)]),
+                "justifications_validators": JustificationValidators(
+                    data=[Boolean(False), Boolean(False)]
+                ),
+            }
+        ),
+        blocks=[
+            BlockSpec(slot=Slot(1)),
+        ],
+        post=None,
+        expected_rejection=ExpectedRejection(
+            reason=RejectionReason.JUSTIFICATION_VOTES_LENGTH_MISMATCH,
+            exact_message=(
+                "Justification vote list length does not equal tracked-root count times "
+                "validator count"
+            ),
+        ),
+    )

tests/consensus/lstar/state_transition/test_zero_hash_justification_root.py

@@ -0,0 +1,59 @@
+"""State Transition: zero-hash justification root guard"""
+
+import pytest
+
+from consensus_testing import (
+    BlockSpec,
+    ExpectedRejection,
+    StateTransitionTestFiller,
+    build_genesis_state,
+)
+from lean_spec.spec.forks import RejectionReason, Slot
+from lean_spec.spec.forks.lstar.containers import JustificationRoots, JustificationValidators
+from lean_spec.spec.ssz import ZERO_HASH, Boolean
+
+pytestmark = pytest.mark.valid_until("Lstar")
+
+
+def test_zero_hash_tracked_justification_root_rejects_block(
+    state_transition_test: StateTransitionTestFiller,
+) -> None:
+    """
+    A tracked justification root equal to the zero hash rejects the block.
+
+    Given
+    -----
+    - 4 validators.
+    - the tracked justification roots hold the zero hash.
+    - the flat vote list holds 4 bits, one full validator round.
+    - the vote list length matches the required layout.
+
+    When
+    ----
+    - a block at slot 1 is processed.
+
+    Then
+    ----
+    - the length guard passes, so the zero-hash guard is reached.
+    - the zero hash marks a skipped slot and cannot track votes.
+    - the block is rejected with ZERO_HASH_JUSTIFICATION_ROOT.
+    - the message states the tracked justification roots contain the zero hash.
+    """
+    state_transition_test(
+        pre=build_genesis_state(num_validators=4).model_copy(
+            update={
+                "justifications_roots": JustificationRoots(data=[ZERO_HASH]),
+                "justifications_validators": JustificationValidators(
+                    data=[Boolean(False), Boolean(False), Boolean(False), Boolean(False)]
+                ),
+            }
+        ),
+        blocks=[
+            BlockSpec(slot=Slot(1)),
+        ],
+        post=None,
+        expected_rejection=ExpectedRejection(
+            reason=RejectionReason.ZERO_HASH_JUSTIFICATION_ROOT,
+            exact_message="Tracked justification roots contain the zero hash",
+        ),
+    )