Merge pull request leanEthereum#18 from tcoratger/containers

containers: add subspec for containers

Author: tcoratger

src/lean_spec/subspecs/chain/config.py

@@ -8,7 +8,7 @@
 from pydantic import BaseModel, ConfigDict
 from typing_extensions import Final
 
-from ..types import BasisPoint, uint64
+from lean_spec.types import BasisPoint, Uint64
 
 # --- Time Parameters ---
 
@@ -73,15 +73,15 @@ class _ChainConfig(BaseModel):
     model_config = ConfigDict(frozen=True, extra="forbid")
 
     # Time Parameters
-    slot_duration_ms: uint64
+    slot_duration_ms: Uint64
     proposer_reorg_cutoff_bps: BasisPoint
     vote_due_bps: BasisPoint
     fast_confirm_due_bps: BasisPoint
     view_freeze_cutoff_bps: BasisPoint
 
     # State List Length Presets
-    historical_roots_limit: uint64
-    validator_registry_limit: uint64
+    historical_roots_limit: Uint64
+    validator_registry_limit: Uint64
 
 
 # The Devnet Chain Configuration.

src/lean_spec/subspecs/containers/__init__.py

@@ -0,0 +1,19 @@
+"""The container types for the Lean consensus specification."""
+
+from .block import Block, BlockBody, BlockHeader, SignedBlock
+from .checkpoint import Checkpoint
+from .config import Config
+from .state import State
+from .vote import SignedVote, Vote
+
+__all__ = [
+    "Block",
+    "BlockBody",
+    "BlockHeader",
+    "Checkpoint",
+    "Config",
+    "SignedBlock",
+    "SignedVote",
+    "State",
+    "Vote",
+]

src/lean_spec/subspecs/containers/block.py

@@ -0,0 +1,75 @@
+"""Block Containers."""
+
+from pydantic import Field
+from typing_extensions import Annotated
+
+from lean_spec.types import Bytes32, StrictBaseModel, Uint64
+
+from ..chain import config
+from .vote import Vote
+
+
+class BlockBody(StrictBaseModel):
+    """The body of a block, containing payload data."""
+
+    votes: Annotated[
+        list[Vote],
+        Field(max_length=config.VALIDATOR_REGISTRY_LIMIT),
+    ]
+    """
+    A list of votes included in the block.
+
+    Note: This will eventually be replaced by aggregated attestations.
+    """
+
+
+class BlockHeader(StrictBaseModel):
+    """The header of a block, containing metadata."""
+
+    slot: Uint64
+    """The slot in which the block was proposed."""
+
+    proposer_index: Uint64
+    """The index of the validator that proposed the block."""
+
+    parent_root: Bytes32
+    """The root of the parent block."""
+
+    state_root: Bytes32
+    """The root of the state after processing the block."""
+
+    body_root: Bytes32
+    """The root of the block's body."""
+
+
+class Block(StrictBaseModel):
+    """Represents a single block in the chain."""
+
+    slot: Uint64
+    """The slot in which the block was proposed."""
+
+    proposer_index: Uint64
+    """The index of the validator that proposed the block."""
+
+    parent_root: Bytes32
+    """The root of the parent block."""
+
+    state_root: Bytes32
+    """The root of the state after applying transactions in this block."""
+
+    body: BlockBody
+    """The block's payload."""
+
+
+class SignedBlock(StrictBaseModel):
+    """A container for a block and the proposer's signature."""
+
+    message: Block
+    """The block data that was signed."""
+
+    signature: Bytes32
+    """
+    The proposer's signature of the block message.
+
+    Note: Bytes32 is a placeholder; the actual signature is much larger.
+    """

src/lean_spec/subspecs/containers/checkpoint.py

@@ -0,0 +1,13 @@
+"""Checkpoint Container."""
+
+from lean_spec.types import Bytes32, StrictBaseModel, Uint64
+
+
+class Checkpoint(StrictBaseModel):
+    """Represents a checkpoint in the chain's history."""
+
+    root: Bytes32
+    """The root hash of the checkpoint's block."""
+
+    slot: Uint64
+    """The slot number of the checkpoint's block."""

src/lean_spec/subspecs/containers/config.py

@@ -0,0 +1,18 @@
+"""Consensus Configuration Container."""
+
+from lean_spec.types import StrictBaseModel, Uint64
+
+
+class Config(StrictBaseModel):
+    """
+    Holds temporary configuration properties for simplified consensus.
+
+    Note: These fields support a simplified round-robin block production
+    in the absence of more complex mechanisms like RANDAO or deposits.
+    """
+
+    num_validators: Uint64
+    """The total number of validators in the network."""
+
+    genesis_time: Uint64
+    """The timestamp of the genesis block."""

src/lean_spec/subspecs/containers/state.py

@@ -0,0 +1,64 @@
+"""State Container."""
+
+from pydantic import Field
+from typing_extensions import Annotated
+
+from lean_spec.subspecs.chain import DEVNET_CONFIG
+from lean_spec.types import Bytes32, StrictBaseModel, Uint64
+
+from .block import BlockHeader
+from .checkpoint import Checkpoint
+from .config import Config
+
+
+class State(StrictBaseModel):
+    """The main consensus state object."""
+
+    # Configuration
+    config: Config
+    """The chain's configuration parameters."""
+
+    # Slot and block tracking
+    slot: Uint64
+    """The current slot number."""
+
+    latest_block_header: BlockHeader
+    """The header of the most recent block."""
+
+    # Fork choice
+    latest_justified: Checkpoint
+    """The latest justified checkpoint."""
+
+    latest_finalized: Checkpoint
+    """The latest finalized checkpoint."""
+
+    # Historical data
+    historical_block_hashes: Annotated[
+        list[Bytes32],
+        Field(max_length=DEVNET_CONFIG.historical_roots_limit),
+    ]
+    """A list of historical block root hashes."""
+
+    justified_slots: Annotated[
+        list[bool],
+        Field(max_length=DEVNET_CONFIG.historical_roots_limit),
+    ]
+    """A bitfield indicating which historical slots were justified."""
+
+    # Justification tracking (flattened for SSZ compatibility)
+    justifications_roots: Annotated[
+        list[Bytes32],
+        Field(max_length=DEVNET_CONFIG.historical_roots_limit),
+    ]
+    """Roots of justified blocks."""
+
+    justifications_validators: Annotated[
+        list[bool],
+        Field(
+            max_length=(
+                DEVNET_CONFIG.historical_roots_limit
+                * DEVNET_CONFIG.historical_roots_limit
+            )
+        ),
+    ]
+    """A bitlist of validators who participated in justifications."""

src/lean_spec/subspecs/containers/vote.py

@@ -0,0 +1,38 @@
+"""Vote Containers."""
+
+from lean_spec.types import Bytes32, StrictBaseModel, Uint64
+
+from .checkpoint import Checkpoint
+
+
+class Vote(StrictBaseModel):
+    """Represents a validator's vote for chain head."""
+
+    validator_id: Uint64
+    """The index of the voting validator."""
+
+    slot: Uint64
+    """The slot for which this vote is cast."""
+
+    head: Checkpoint
+    """The validator's perceived head of the chain."""
+
+    target: Checkpoint
+    """The justified checkpoint the validator is voting for."""
+
+    source: Checkpoint
+    """The last justified checkpoint known to the validator."""
+
+
+class SignedVote(StrictBaseModel):
+    """A container for a vote and its corresponding signature."""
+
+    data: Vote
+    """The vote data."""
+
+    signature: Bytes32
+    """
+    The signature of the vote data.
+
+    Note: Bytes32 is a placeholder; the actual signature is much larger.
+    """

src/lean_spec/subspecs/types/__init__.py

@@ -0,0 +1,13 @@
+"""Reusable type definitions for the Lean Ethereum specification."""
+
+from .base import StrictBaseModel
+from .basispt import BasisPoint
+from .hash import Bytes32
+from .uint64 import Uint64
+
+__all__ = [
+    "Uint64",
+    "BasisPoint",
+    "Bytes32",
+    "StrictBaseModel",
+]

src/lean_spec/types/__init__.py

@@ -0,0 +1,9 @@
+"""Reusable, strict base models for the specification."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class StrictBaseModel(BaseModel):
+    """A strict, immutable pydantic base model."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")