fix(stf): keep the 3SF-mini justifiability rule under the heartbeat fork choice

The heartbeat work had dropped `slot_is_justifiable_after` and collapsed
finalization to `source.slot + 1 == target.slot`. Restore the rule: the two-tier
fork choice changes which head each interval computes, not which slots may be
justified, so the two are independent.

Unjustifiable slots exist to funnel votes. Under high latency validators
otherwise spread across many targets and none reaches a supermajority; the
4-interval grid does not remove that pressure.

Restored at the four sites that had diverged:

- `is_valid_vote` filters targets that are not justifiable after the finalized
  slot. Its doc comment had kept listing the check, so the code and the contract
  had drifted apart.
- `try_finalize` requires no justifiable slot strictly between source and
  target, rather than plain adjacency.
- `get_attestation_target_with_checkpoints` walks the target back into the
  justifiable range again, making `finalized` a live parameter once more.
- The block builder mirrors both: `finalizes` uses the gap scan and
  `entry_passes_filters` rejects `target_not_justifiable`.

The test added to pin the adjacency rule still holds under 3SF-mini, for the
reason the rule gives rather than by adjacency, and is renamed to say so.

stf_spectests returns to 74/74 and forkchoice_spectests to 97/122. The 25
remaining failures are the interval grid and the two-tier head, which the
fixtures do not encode yet.

Author: MegaRedHand

crates/blockchain/src/block_builder.rs

@@ -18,7 +18,7 @@ use std::{
 use ethlambda_crypto::{aggregate_proofs, signature::ValidatorPublicKey};
 use ethlambda_state_transition::{
     attestation_data_matches_chain, is_heartbeat_committee_member, justified_slots_ops,
-    process_block, process_slots,
+    process_block, process_slots, slot_is_justifiable_after,
 };
 use ethlambda_types::{
     ShortRoot,
@@ -480,14 +480,16 @@ impl ProjectedState {
         let total = prior_count + new_voters.len();
         let crosses_2_3 = 3 * total >= 2 * validator_count;
 
-        // The simple BFT finality condition finalizes the source when it lies past
-        // the finalized boundary (a source at or behind it is already final and must
-        // not re-finalize) and the target is its immediate successor, so the two are
-        // consecutive justified checkpoints in the projected post-state. Mirrors
+        // 3SF-mini finalization requires the source to lie past the finalized
+        // boundary (a source at or behind it is already final and must not
+        // re-finalize) and no slot strictly between source.slot and target.slot
+        // to still be justifiable (so source and target are consecutive
+        // justified checkpoints in the projected post-state). Mirrors
         // `try_finalize` in the state transition.
         let finalizes = crosses_2_3
             && att_data.source.slot > self.finalized_slot
-            && att_data.source.slot + 1 == att_data.target.slot;
+            && (att_data.source.slot + 1..att_data.target.slot)
+                .all(|s| !slot_is_justifiable_after(s, self.finalized_slot));
 
         let effect = if is_genesis_self_vote(att_data) || !crosses_2_3 {
             EntryEffect::Builds
@@ -523,8 +525,9 @@ impl ProjectedState {
     ///
     /// Mirrors `state_transition::is_valid_vote`: the entry's head must be
     /// known, its source must be justified, its (source, target) must match
-    /// the candidate-block chain view, `target.slot > source.slot`, and target
-    /// must not already be justified. The genesis self-vote
+    /// the candidate-block chain view, `target.slot > source.slot`, target
+    /// must not already be justified, and target must be a justifiable slot
+    /// relative to the projected finalized slot. The genesis self-vote
     /// (source == target == slot 0) is exempt from the `target.slot >
     /// source.slot` and `target_already_justified` checks since fork-choice
     /// bootstrapping needs it; STF will silently drop it, but it carries
@@ -561,6 +564,11 @@ impl ProjectedState {
         {
             return Err("target_already_justified");
         }
+        if !is_genesis_self_vote
+            && !slot_is_justifiable_after(att_data.target.slot, self.finalized_slot)
+        {
+            return Err("target_not_justifiable");
+        }
         Ok(())
     }
 }

crates/blockchain/src/store.rs

@@ -3,6 +3,7 @@ use std::collections::{HashMap, HashSet};
 use ethlambda_crypto::signature::{ValidatorPublicKey, ValidatorSignature};
 use ethlambda_state_transition::{
     effective_heartbeat_committee_size, is_heartbeat_committee_member, is_proposer,
+    slot_is_justifiable_after,
 };
 use ethlambda_storage::{ForkCheckpoints, Store};
 use ethlambda_types::{
@@ -1052,15 +1053,11 @@ pub fn get_attestation_target(store: &Store) -> Checkpoint {
 /// Note: the walk-back still starts from `store.head()` (the pre-import head), not
 /// the new block. This is correct because the new block is only 1 slot ahead with less than 2/3 of votes — the
 /// walk-back immediately reaches the same chain. The important fix is using the
-/// post-state justified for the clamping guard.
+/// post-state justified/finalized for the justifiability check and clamping guard.
 pub fn get_attestation_target_with_checkpoints(
     store: &Store,
     justified: Checkpoint,
-    // Unused under the simple BFT finality condition: every slot is justifiable
-    // now, so the target no longer needs a justifiability walk-back. Kept on the
-    // signature because callers resolve both checkpoints from the same
-    // post-state and the pair reads as one unit.
-    _finalized: Checkpoint,
+    finalized: Checkpoint,
 ) -> Checkpoint {
     // Start from current head
     let mut target_block_root = store.head().unwrap();
@@ -1091,6 +1088,22 @@ pub fn get_attestation_target_with_checkpoints(
         }
     }
 
+    let finalized_slot = finalized.slot;
+
+    // Ensure target is in justifiable slot range
+    //
+    // Walk back until we find a slot that satisfies justifiability rules
+    // relative to the latest finalized checkpoint.
+    while target_header.slot > finalized_slot
+        && !slot_is_justifiable_after(target_header.slot, finalized_slot)
+    {
+        target_block_root = target_header.parent_root;
+        target_header = store
+            .get_block_header(&target_block_root)
+            .expect("parent block exists")
+            .unwrap();
+    }
+
     // Guard: clamp target to justified (not in the spec).
     //
     // The spec's walk-back has no lower bound, so it can produce attestations

crates/blockchain/state_transition/src/lib.rs

@@ -485,17 +485,22 @@ fn is_valid_vote(state: &State, data: &AttestationData) -> bool {
         return false;
     }
 
+    // Ensure the target falls on a slot that can be justified after the finalized one.
+    if !slot_is_justifiable_after(target.slot, state.latest_finalized.slot) {
+        return false;
+    }
+
     true
 }
 
 /// Attempt to advance finalization from source to target.
 ///
 /// Finalization advances only when the source lies past the old finalized point
-/// and the target is the source's immediate successor, so the two are
-/// consecutive justified checkpoints. A source at or behind the finalized
-/// boundary is already final: it may justify a newer target, but it must not
-/// re-finalize. When finalization advances, shifts the justified_slots window
-/// and prunes stale justifications.
+/// and there are no justifiable slots between source.slot and target.slot
+/// (exclusive). A source at or behind the finalized boundary is already final:
+/// it may justify a newer target, but it must not re-finalize or scan below the
+/// finalized boundary. When finalization advances, shifts the justified_slots
+/// window and prunes stale justifications.
 fn try_finalize(
     state: &mut State,
     source: Checkpoint,
@@ -509,10 +514,10 @@ fn try_finalize(
         return;
     }
 
-    // Consider whether finalization can advance. Every slot is justifiable now,
-    // so "no justifiable slot strictly between source and target" collapses to
-    // the two being adjacent.
-    if source.slot + 1 != target.slot {
+    // Consider whether finalization can advance.
+    if ((source.slot + 1)..target.slot)
+        .any(|slot| slot_is_justifiable_after(slot, state.latest_finalized.slot))
+    {
         metrics::inc_finalizations("error");
         return;
     }
@@ -621,6 +626,47 @@ pub fn attestation_data_matches_chain(
         && historical_block_hashes[head_slot] == data.head.root
 }
 
+/// Checks if the slot is a valid candidate for justification after a given finalized slot.
+///
+/// According to the 3SF-mini specification, a slot is justifiable if its
+/// distance (`delta`) from the last finalized slot is:
+///     1. Less than or equal to 5.
+///     2. A perfect square (e.g., 9, 16, 25...).
+///     3. A pronic number (of the form x^2 + x, e.g., 6, 12, 20...).
+///
+/// See https://github.com/ethereum/research/blob/c003fe1c1a785797e7b53e3cbf9569b989be6e93/3sf-mini/consensus.py#L52-L54
+/// for the 3SF-mini reference.
+///
+/// For why we have unjustifiable slots, consider that in high-latency
+/// scenarios, validators may vote for many different slots, making none of them
+/// reach the supermajority threshold. By having unjustifiable slots, we can
+/// funnel votes towards only some slots, increasing finalization chances.
+pub fn slot_is_justifiable_after(slot: u64, finalized_slot: u64) -> bool {
+    let Some(delta) = slot.checked_sub(finalized_slot) else {
+        // Candidate slot must not be before finalized slot
+        return false;
+    };
+    // Rule 1: The first 5 slots after finalization are always justifiable.
+    //
+    // Examples: delta = 0, 1, 2, 3, 4, 5
+    delta <= 5
+        // Rule 2: Slots at perfect square distances are justifiable.
+        //
+        // Examples: delta = 1, 4, 9, 16, 25, 36, 49, 64, ...
+        // Check: integer square root squared equals delta
+        || delta.isqrt().pow(2) == delta
+        // Rule 3: Slots at pronic number distances are justifiable.
+        //
+        // Pronic numbers have the form n(n+1): 2, 6, 12, 20, 30, 42, 56, ...
+        // Mathematical insight: For pronic delta = n(n+1), we have:
+        //   4*delta + 1 = 4n(n+1) + 1 = (2n+1)^2
+        // Check: 4*delta+1 is an odd perfect square
+        || delta
+            .checked_mul(4)
+            .and_then(|v| v.checked_add(1))
+            .is_some_and(|val| val.isqrt().pow(2) == val && val % 2 == 1)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -706,10 +752,11 @@ mod tests {
     }
 
     #[test]
-    fn finalization_requires_adjacent_source_and_target() {
-        // The simple BFT condition: only consecutive checkpoints finalize. Pinned
-        // here because the 3SF-mini justifiability rules that used to gate this
-        // are gone.
+    fn finalization_blocked_by_justifiable_slot_between_source_and_target() {
+        // Source and target must be *consecutive justified checkpoints*, which
+        // under 3SF-mini means no slot strictly between them is still justifiable
+        // relative to the finalized boundary. Here slot 4 is (delta = 4 <= 5), so
+        // the pair is not consecutive and finalization must not advance.
         let mut state = State::from_genesis(0, make_validators(4));
         state.latest_finalized = Checkpoint {
             root: H256::ZERO,
@@ -732,7 +779,10 @@ mod tests {
             &mut justifications,
             &root_to_slot,
         );
-        assert_eq!(state.latest_finalized.slot, 0, "gap must not finalize");
+        assert_eq!(
+            state.latest_finalized.slot, 0,
+            "justifiable slot between source and target must not finalize"
+        );
     }
 
     fn make_validators(n: usize) -> Vec<Validator> {