chore: uint base types and skeleton for ssz (leanEthereum#34)

* chore: uint base types and skeleton for ssz

* some fix - wip

* fix tests

* fix silent truncation of floats

* add max method

* fix constructor

* Update src/lean_spec/types/uint.py

Co-authored-by: felipe <fselmo2@gmail.com>

* add pydantic checks

* fix some operations and tests

* fix max method

* fix max

* add test for max method

---------

Co-authored-by: felipe <fselmo2@gmail.com>

Author: tcoratger

src/lean_spec/subspecs/chain/config.py

@@ -12,16 +12,16 @@
 
 # --- Time Parameters ---
 
-SLOT_DURATION_MS: Final = 4000
+SLOT_DURATION_MS: Final = Uint64(4000)
 """The fixed duration of a single slot in milliseconds."""
 
-SECONDS_PER_SLOT: Final = SLOT_DURATION_MS // 1000
+SECONDS_PER_SLOT: Final = SLOT_DURATION_MS // Uint64(1000)
 """The fixed duration of a single slot in seconds."""
 
-JUSTIFICATION_LOOKBACK_SLOTS: Final = 3
+JUSTIFICATION_LOOKBACK_SLOTS: Final = Uint64(3)
 """The number of slots to lookback for justification."""
 
-PROPOSER_REORG_CUTOFF_BPS: Final = 2500
+PROPOSER_REORG_CUTOFF_BPS: Final = Uint64(2500)
 """
 The deadline within a slot (in basis points) for a proposer to publish a
 block.
@@ -31,23 +31,23 @@
 (2500 bps = 25% of slot duration).
 """
 
-VOTE_DUE_BPS: Final = 5000
+VOTE_DUE_BPS: Final = Uint64(5000)
 """
 The deadline within a slot (in basis points) by which validators must
 submit their votes.
 
 (5000 bps = 50% of slot duration).
 """
 
-FAST_CONFIRM_DUE_BPS: Final = 7500
+FAST_CONFIRM_DUE_BPS: Final = Uint64(7500)
 """
 The deadline within a slot (in basis points) for achieving a fast
 confirmation.
 
 (7500 bps = 75% of slot duration).
 """
 
-VIEW_FREEZE_CUTOFF_BPS: Final = 7500
+VIEW_FREEZE_CUTOFF_BPS: Final = Uint64(7500)
 """
 The cutoff within a slot (in basis points) after which the current view is
 considered 'frozen', preventing further changes.
@@ -57,15 +57,15 @@
 
 # --- State List Length Presets ---
 
-HISTORICAL_ROOTS_LIMIT: Final = 2**18
+HISTORICAL_ROOTS_LIMIT: Final = Uint64(2**18)
 """
 The maximum number of historical block roots to store in the state.
 
 With a 4-second slot, this corresponds to a history
 of approximately 12.1 days.
 """
 
-VALIDATOR_REGISTRY_LIMIT: Final = 2**12
+VALIDATOR_REGISTRY_LIMIT: Final = Uint64(2**12)
 """The maximum number of validators that can be in the registry."""
 
 

src/lean_spec/subspecs/containers/state.py

@@ -99,7 +99,7 @@ def get_justifications(self) -> Dict[Bytes32, List[bool]]:
         # Cache the validator registry limit for concise slicing calculations.
         #
         # This value determines the size of the block of votes for each root.
-        limit = DEVNET_CONFIG.validator_registry_limit
+        limit = DEVNET_CONFIG.validator_registry_limit.as_int()
 
         # Build the entire justifications map.
         return {
@@ -134,7 +134,7 @@ def set_justifications(self, justifications: Dict[Bytes32, List[bool]]) -> None:
         new_roots: List[Bytes32] = []
         # It will store the single, concatenated list of all votes.
         flat_votes: List[bool] = []
-        limit = DEVNET_CONFIG.validator_registry_limit
+        limit = DEVNET_CONFIG.validator_registry_limit.as_int()
 
         # Iterate through the roots in sorted order for deterministic output.
         for root in sorted(justifications.keys()):

src/lean_spec/subspecs/ssz/__init__.py

@@ -0,0 +1 @@
+"""SSZ (Simple Serialize) implementation."""

src/lean_spec/subspecs/ssz/constants.py

@@ -0,0 +1,7 @@
+"""Constants defined in the SSZ specification."""
+
+BYTES_PER_CHUNK: int = 32
+"""The number of bytes in a Merkle tree chunk."""
+
+ZERO_HASH: bytes = b"\x00" * BYTES_PER_CHUNK
+"""A zero hash, used for padding in the Merkle tree."""

src/lean_spec/subspecs/ssz/gindex.py

@@ -0,0 +1,50 @@
+"""Generalized Index implementation."""
+
+from typing import List
+
+from pydantic import BaseModel, Field
+
+
+class GeneralizedIndex(BaseModel):
+    """
+    Represents a Generalized Merkle Tree Index.
+
+    Helper methods are provided for tree navigation.
+    """
+
+    value: int = Field(..., gt=0, description="The index value, must be a positive integer.")
+
+    @property
+    def depth(self) -> int:
+        """The depth of the node in the tree."""
+        return self.value.bit_length() - 1
+
+    def get_bit(self, position: int) -> bool:
+        """Returns the bit at a specific position (from the right)."""
+        return (self.value >> position) & 1 == 1
+
+    @property
+    def sibling(self) -> "GeneralizedIndex":
+        """Returns the index of the sibling node."""
+        return type(self)(value=self.value ^ 1)
+
+    @property
+    def parent(self) -> "GeneralizedIndex":
+        """Returns the index of the parent node."""
+        if self.value <= 1:
+            raise ValueError("Root node has no parent.")
+        return type(self)(value=self.value // 2)
+
+    def get_branch_indices(self) -> List["GeneralizedIndex"]:
+        """Gets the indices of the sibling nodes along the path to the root."""
+        indices = [self.sibling]
+        while indices[-1].value > 1:
+            indices.append(indices[-1].parent.sibling)
+        return indices[:-1]
+
+    def get_path_indices(self) -> List["GeneralizedIndex"]:
+        """Gets the indices of the nodes along the path to the root."""
+        indices: List["GeneralizedIndex"] = [self]
+        while indices[-1].value > 1:
+            indices.append(indices[-1].parent)
+        return indices[:-1]

src/lean_spec/subspecs/xmss/interface.py

@@ -15,6 +15,7 @@
     TEST_TARGET_SUM_ENCODER,
     TargetSumEncoder,
 )
+from lean_spec.types.uint import Uint64
 
 from .constants import (
     PROD_CONFIG,
@@ -117,7 +118,7 @@ def key_gen(self, activation_epoch: int, num_active_epochs: int) -> Tuple[Public
                 # Derive the secret start of the chain from the master PRF key.
                 #
                 # This ensures each chain is unique and cryptographically secure.
-                start_digest = self.prf.apply(prf_key, epoch, chain_index)
+                start_digest = self.prf.apply(prf_key, epoch, Uint64(chain_index))
 
                 # Compute the public end of the chain by applying the hash function
                 # `BASE - 1` times. This is the public part of the one-time key.
@@ -234,7 +235,7 @@ def sign(self, sk: SecretKey, epoch: int, message: bytes) -> Signature:
         ots_hashes: List[HashDigest] = []
         for chain_index, steps in enumerate(codeword):
             # Derive the secret start of the current chain using the master PRF key.
-            start_digest = self.prf.apply(sk.prf_key, epoch, chain_index)
+            start_digest = self.prf.apply(sk.prf_key, epoch, Uint64(chain_index))
             # Walk the hash chain for the number of `steps` specified by the
             # corresponding digit in the codeword.
             #

src/lean_spec/subspecs/xmss/prf.py

@@ -14,7 +14,7 @@
 from typing import List
 
 from lean_spec.subspecs.koalabear import Fp
-from lean_spec.types.uint64 import Uint64
+from lean_spec.types.uint import Uint64
 
 from .constants import (
     PRF_KEY_LENGTH,

src/lean_spec/types/__init__.py

@@ -3,7 +3,7 @@
 from .base import StrictBaseModel
 from .basispt import BasisPoint
 from .hash import Bytes32
-from .uint64 import Uint64
+from .uint import Uint64
 from .validator import ValidatorIndex
 
 __all__ = [

src/lean_spec/types/basispt.py

@@ -3,11 +3,11 @@
 from pydantic import Field
 from typing_extensions import Annotated
 
-from ..types.uint64 import Uint64
+from .uint import Uint64
 
 BasisPoint = Annotated[
     Uint64,
-    Field(le=10000, description="A value in basis points (1/10000)."),
+    Field(le=Uint64(10000), description="A value in basis points (1/10000)."),
 ]
 """
 A type alias for basis points.