refactor(types/uint): polish base uint type (leanEthereum#769)

* fix(types/uint): enforce strict same-type equality across widths

The hash mixes in the concrete subclass, so allowing cross-width equality
broke the hash/eq contract: Uint8(5) == Uint16(5) returned True while
hash(Uint8(5)) != hash(Uint16(5)), silently corrupting set and dict
membership. Tighten __eq__ and __ne__ to require type(other) is type(self)
and add parametrized tests covering every ordered pair of distinct widths.

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

* refactor(types/uint): require exact-same-concrete-type on all binary ops

Every BaseUint binary operator now uses type(other) is type(self) instead
of isinstance(other, BaseUint). Previously, Uint8(5) + Uint16(10) silently
produced Uint8(15) because the result type defaulted to the LHS. Now any
cross-width or cross-newtype mixing raises TypeError, matching how a
strongly typed language rejects u8 + u16 or Slot + Uint64.

Also in this commit:
- __rpow__ gains the missing mod parameter for 3-arg pow.
- __pow__ uses overloads to express the parent's two-overload return shape.
- Dead _validate_int_operand helper removed (no callers remain).
- Class docstring documents the universal strict-type rule.

Consumers throughout the chain/clock, fork-choice, validator service, and
xmss code that were silently relying on cross-type interop are updated to
convert explicitly via int() or the appropriate newtype constructor.

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

* docs(types/uint): tighten docstrings and comments per /doc rules

Strip backticks, drop restated-code prose, collapse multi-line docstrings to
single-sentence summaries where the signature already documents the rest, and
fix two factually wrong Raises sections that cited non-existent error types.

Add brief Why comments to the Pydantic schema body where the plumbing is
non-obvious.

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

* test(types/uint): full-message error matching and 100% coverage

Every pytest.raises now anchors on the exact exception message via
re.escape, replacing partial or wildcard matches that could silently
accept the wrong error.

Add tests for the previously-untested three-argument reverse pow paths
(both the success path and the modulo type-rejection branch), lifting
uint.py coverage to 100%.

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

* docs(chain/clock): trim redundant strict-typing comment in from_slot

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

* fix(testing/store_checks): type StoreChecks.time as Interval

Store.time is an Interval; the StoreChecks comparison field was still
typed as Uint64, which under the strict-typing rule causes Interval !=
Uint64 to raise TypeError during fixture validation. Update the field
to Interval and the two test call sites that constructed Uint64 values.

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

---------

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

Author: tcoratger

packages/testing/src/consensus_testing/test_fixtures/slot_clock.py

@@ -13,7 +13,7 @@
     MILLISECONDS_PER_INTERVAL,
     SECONDS_PER_SLOT,
 )
-from lean_spec.types import Uint64
+from lean_spec.types import Slot, Uint64
 
 from .base import BaseConsensusFixture
 
@@ -72,7 +72,7 @@ def _make_from_unix_time(self) -> dict[str, Any]:
 
     def _make_from_slot(self) -> dict[str, Any]:
         """Convert slot number to interval at that slot's start."""
-        slot = Uint64(self.input["slot"])
+        slot = Slot(self.input["slot"])
         interval = Interval.from_slot(slot)
         return {"interval": int(interval)}
 

packages/testing/src/consensus_testing/test_types/store_checks.py

@@ -6,8 +6,9 @@
 from lean_spec.forks.lstar.containers.block.block import Block
 from lean_spec.forks.lstar.spec import LstarSpec
 from lean_spec.forks.lstar.store import Store
+from lean_spec.subspecs.chain.clock import Interval
 from lean_spec.subspecs.ssz import hash_tree_root
-from lean_spec.types import ZERO_HASH, Bytes32, CamelModel, Slot, Uint64, ValidatorIndex
+from lean_spec.types import ZERO_HASH, Bytes32, CamelModel, Slot, ValidatorIndex
 
 from .utils import resolve_block_root
 
@@ -123,7 +124,7 @@ class StoreChecks(CamelModel):
     This allows tests to focus on the properties they care about.
     """
 
-    time: Uint64 | None = None
+    time: Interval | None = None
     """Expected store time (in intervals since genesis)."""
 
     head_slot: Slot | None = None

src/lean_spec/forks/lstar/spec.py

@@ -1092,7 +1092,8 @@ def validate_attestation(self, store: LstarStore, attestation_data: AttestationD
         # let an adversary pre-publish next-slot aggregates ahead of any
         # honest validator.
         attestation_start_interval = Interval.from_slot(data.slot)
-        assert attestation_start_interval <= store.time + GOSSIP_DISPARITY_INTERVALS, (
+        gossip_disparity = Interval(int(GOSSIP_DISPARITY_INTERVALS))
+        assert attestation_start_interval <= store.time + gossip_disparity, (
             "Attestation too far in future"
         )
 
@@ -1761,7 +1762,7 @@ def tick_interval(
         """
         # Advance time by one interval
         store = store.model_copy(update={"time": store.time + Interval(1)})
-        current_interval = store.time % INTERVALS_PER_SLOT
+        current_interval = Interval(int(store.time) % int(INTERVALS_PER_SLOT))
         new_aggregates: list[SignedAggregatedAttestation] = []
 
         if current_interval == Interval(0) and has_proposal:

src/lean_spec/subspecs/chain/clock.py

@@ -53,7 +53,7 @@ def from_unix_time(cls, unix_seconds: Uint64, genesis_time: Uint64) -> Interval:
         return cls(delta_ms // MILLISECONDS_PER_INTERVAL)
 
     @classmethod
-    def from_slot(cls, slot: Uint64) -> Interval:
+    def from_slot(cls, slot: Slot) -> Interval:
         """
         Convert a slot number to the interval at that slot's start.
 
@@ -67,7 +67,7 @@ def from_slot(cls, slot: Uint64) -> Interval:
             Interval count at the start of the given slot.
         """
         # Slot boundaries fall on exact multiples of the interval count.
-        return cls(slot * INTERVALS_PER_SLOT)
+        return cls(int(slot) * int(INTERVALS_PER_SLOT))
 
 
 @dataclass(frozen=True, slots=True)

src/lean_spec/subspecs/chain/service.py

@@ -29,7 +29,6 @@
 from lean_spec.forks import LstarSpec, SignedAggregatedAttestation
 from lean_spec.subspecs.chain.config import INTERVALS_PER_SLOT
 from lean_spec.subspecs.sync import SyncService
-from lean_spec.types import Uint64
 
 from .clock import Interval, SlotClock
 
@@ -167,9 +166,10 @@ async def _tick_to(self, target_interval: Interval) -> list[SignedAggregatedAtte
         # Jump to the last full slot boundary before the target.
         # The final slot's worth of intervals still runs normally so that
         # aggregation, safe target, and attestation acceptance happen.
+        intervals_per_slot = Interval(int(INTERVALS_PER_SLOT))
         gap = target_interval - store.time
-        if gap > INTERVALS_PER_SLOT:
-            skip_to = Uint64(target_interval - INTERVALS_PER_SLOT)
+        if gap > intervals_per_slot:
+            skip_to = target_interval - intervals_per_slot
             store = store.model_copy(update={"time": skip_to})
             self.sync_service.store = store
 

src/lean_spec/subspecs/validator/service.py

@@ -165,7 +165,7 @@ async def run(self) -> None:
                 my_indices,
             )
 
-            if interval == Uint64(0):
+            if interval == Interval(0):
                 # Block production interval.
                 #
                 # Check if any of our validators is the proposer.
@@ -204,7 +204,7 @@ async def run(self) -> None:
             # Why split eligibility from the sync gate: the skip counter
             # must only tick on real misses, never on wrong-interval
             # iterations.
-            needs_attestation = interval >= Uint64(1) and slot not in self._attested_slots
+            needs_attestation = interval >= Interval(1) and slot not in self._attested_slots
             if needs_attestation:
                 logger.debug(
                     "ValidatorService: producing attestations for slot %d (interval %d)",

src/lean_spec/subspecs/xmss/interface.py

@@ -117,7 +117,7 @@ def key_gen(self, activation_slot: Slot, num_active_slots: Uint64) -> KeyPair:
         config = self.config
 
         # Ensure the requested activation range is within the scheme's total supported lifetime.
-        if activation_slot + num_active_slots > config.LIFETIME:
+        if int(activation_slot) + int(num_active_slots) > int(config.LIFETIME):
             raise ValueError("Activation range exceeds the key's lifetime.")
 
         # Generate the random public parameter `P` and the master PRF key.
@@ -330,7 +330,7 @@ def sign(self, sk: SecretKey, slot: Slot, message: Bytes32) -> Signature:
         bottom_tree = sk.left_bottom_tree if slot_int < boundary else sk.right_bottom_tree
 
         # Generate the combined authentication path
-        path = combined_path(sk.top_tree, bottom_tree, slot)
+        path = combined_path(sk.top_tree, bottom_tree, Uint64(int(slot)))
 
         # Assemble and return the final signature, which contains:
         # - The OTS,
@@ -385,7 +385,7 @@ def verify(self, pk: PublicKey, slot: Slot, message: Bytes32, sig: Signature) ->
         #
         # Return False instead of raising to avoid panic on invalid signatures.
         # The slot is attacker-controlled input.
-        if slot >= self.config.LIFETIME:
+        if int(slot) >= int(self.config.LIFETIME):
             return False
 
         # Re-encode the message using the randomness `rho` from the signature.