dynamic validator set

src/lean_spec/subspecs/chain/config.py

@@ -37,6 +37,45 @@
 VALIDATOR_REGISTRY_LIMIT: Final = Uint64(2**12)
 """The maximum number of validators that can be in the registry."""
 
+# --- Validator Lifecycle Parameters ---
+
+MIN_ACTIVATION_DELAY: Final = Uint64(8)
+"""
+Minimum number of slots a validator must wait before activation.
+
+This delay ensures:
+1. The deposit is finalized before activation
+2. Network participants see the deposit before validator is active
+3. Time for validation and consensus on the new validator
+"""
+
+MIN_EXIT_DELAY: Final = Uint64(8)
+"""
+Minimum number of slots from exit request to actual removal.
+
+This delay ensures:
+1. Ongoing attestations from exiting validator can complete
+2. Chain stability during validator set changes
+3. Clean handoff of validator responsibilities
+"""
+
+MAX_ACTIVATIONS_PER_SLOT: Final = Uint64(4)
+"""
+Maximum number of validators that can activate in a single slot.
+
+Rate limiting prevents:
+1. Sudden validator set size changes
+2. State bloat from mass activations
+3. Consensus instability from rapid composition changes
+"""
+
+MAX_EXITS_PER_SLOT: Final = Uint64(4)
+"""
+Maximum number of validators that can exit in a single slot.
+
+Similar to activation limiting, this ensures gradual validator set changes.
+"""
+
 
 class _ChainConfig(StrictBaseModel):
     """
@@ -52,11 +91,21 @@ class _ChainConfig(StrictBaseModel):
     historical_roots_limit: Uint64
     validator_registry_limit: Uint64
 
+    # Validator Lifecycle Parameters
+    min_activation_delay: Uint64
+    min_exit_delay: Uint64
+    max_activations_per_slot: Uint64
+    max_exits_per_slot: Uint64
+
 
 # The Devnet Chain Configuration.
 DEVNET_CONFIG: Final = _ChainConfig(
     seconds_per_slot=SECONDS_PER_SLOT,
     justification_lookback_slots=JUSTIFICATION_LOOKBACK_SLOTS,
     historical_roots_limit=HISTORICAL_ROOTS_LIMIT,
     validator_registry_limit=VALIDATOR_REGISTRY_LIMIT,
+    min_activation_delay=MIN_ACTIVATION_DELAY,
+    min_exit_delay=MIN_EXIT_DELAY,
+    max_activations_per_slot=MAX_ACTIVATIONS_PER_SLOT,
+    max_exits_per_slot=MAX_EXITS_PER_SLOT,
 )

src/lean_spec/subspecs/containers/block/block.py

@@ -11,6 +11,8 @@
 
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 from lean_spec.subspecs.containers.slot import Slot
 from lean_spec.subspecs.xmss.aggregation import AggregationError
 from lean_spec.subspecs.xmss.interface import TARGET_SIGNATURE_SCHEME, GeneralizedXmssScheme
@@ -19,6 +21,8 @@
 
 from ...xmss.containers import Signature as XmssSignature
 from ..attestation import Attestation
+from ..deposit import ValidatorDeposits
+from ..exit import ValidatorExits
 from .types import (
     AggregatedAttestations,
     AttestationSignatures,
@@ -32,8 +36,8 @@ class BlockBody(Container):
     """
     The body of a block, containing payload data.
 
-    Currently, the main operation is voting. Validators submit attestations which are
-    packaged into blocks.
+    Contains validator votes (attestations) and validator lifecycle operations
+    (deposits and exits).
     """
 
     attestations: AggregatedAttestations
@@ -43,6 +47,12 @@ class BlockBody(Container):
     these entries contain only attestation data without per-attestation signatures.
     """
 
+    deposits: ValidatorDeposits = Field(default_factory=lambda: ValidatorDeposits(data=[]))
+    """Validator deposit operations for new validators joining."""
+
+    exits: ValidatorExits = Field(default_factory=lambda: ValidatorExits(data=[]))
+    """Validator exit operations for validators leaving."""
+
 
 class BlockHeader(Container):
     """

src/lean_spec/subspecs/containers/config.py

@@ -14,3 +14,15 @@ class Config(Container):
 
     genesis_time: Uint64
     """The timestamp of the genesis block."""
+
+    min_activation_delay: Uint64 = Uint64(8)
+    """Minimum slots before a validator deposit activates."""
+
+    min_exit_delay: Uint64 = Uint64(8)
+    """Minimum slots before a validator exit is removed."""
+
+    max_activations_per_slot: Uint64 = Uint64(4)
+    """Maximum validators that can activate in one slot."""
+
+    max_exits_per_slot: Uint64 = Uint64(4)
+    """Maximum validators that can exit in one slot."""

src/lean_spec/subspecs/containers/deposit/__init__.py

@@ -0,0 +1,6 @@
+"""Validator deposit container types."""
+
+from .deposit import PendingDeposit, ValidatorDeposit
+from .types import ValidatorDeposits
+
+__all__ = ["PendingDeposit", "ValidatorDeposit", "ValidatorDeposits"]

src/lean_spec/subspecs/containers/deposit/deposit.py

@@ -0,0 +1,40 @@
+"""
+Validator deposit operation definitions.
+
+Deposits are how new validators join the network.
+A ValidatorDeposit operation specifies a validator's XMSS public key.
+The deposit enters a pending queue and activates after a delay.
+"""
+
+from __future__ import annotations
+
+from lean_spec.types import Bytes52, Container
+
+from ..slot import Slot
+
+
+class ValidatorDeposit(Container):
+    """
+    Operation for registering a new validator.
+
+    Validators submit their XMSS public key to join the network.
+    The deposit is added to a pending queue and activates after MIN_ACTIVATION_DELAY slots.
+    """
+
+    pubkey: Bytes52
+    """The XMSS public key for the new validator."""
+
+
+class PendingDeposit(Container):
+    """
+    A validator deposit awaiting activation.
+
+    Tracks when the deposit was included in a block.
+    The deposit becomes active after MIN_ACTIVATION_DELAY slots from queued_slot.
+    """
+
+    pubkey: Bytes52
+    """The XMSS public key for the validator."""
+
+    queued_slot: Slot
+    """The slot when this deposit was included in a block."""

src/lean_spec/subspecs/containers/deposit/types.py

@@ -0,0 +1,15 @@
+"""Deposit-specific SSZ types for the Lean Ethereum consensus specification."""
+
+from __future__ import annotations
+
+from lean_spec.types import SSZList
+
+from ...chain.config import VALIDATOR_REGISTRY_LIMIT
+from .deposit import ValidatorDeposit
+
+
+class ValidatorDeposits(SSZList[ValidatorDeposit]):
+    """List of validator deposits included in a block."""
+
+    ELEMENT_TYPE = ValidatorDeposit
+    LIMIT = int(VALIDATOR_REGISTRY_LIMIT)

src/lean_spec/subspecs/containers/exit/__init__.py

@@ -0,0 +1,6 @@
+"""Validator exit container types."""
+
+from .exit import ExitRequest, ValidatorExit
+from .types import ValidatorExits
+
+__all__ = ["ExitRequest", "ValidatorExit", "ValidatorExits"]

src/lean_spec/subspecs/containers/exit/exit.py

@@ -0,0 +1,40 @@
+"""
+Validator exit operation definitions.
+
+Exits are how validators leave the network.
+A ValidatorExit operation signals a validator's intent to leave.
+The exit enters a queue and the validator is removed after a delay.
+"""
+
+from __future__ import annotations
+
+from lean_spec.types import Container, Uint64
+
+from ..slot import Slot
+
+
+class ValidatorExit(Container):
+    """
+    Operation for a validator to request exit from the active set.
+
+    Validators signal their intent to leave the network.
+    The exit is added to a queue and the validator is removed after MIN_EXIT_DELAY slots.
+    """
+
+    validator_index: Uint64
+    """The index of the validator requesting exit."""
+
+
+class ExitRequest(Container):
+    """
+    A validator exit request in the queue.
+
+    Tracks when the exit was requested.
+    The validator is removed after MIN_EXIT_DELAY slots from exit_slot.
+    """
+
+    validator_index: Uint64
+    """The index of the validator requesting exit."""
+
+    exit_slot: Slot
+    """The slot when the exit was requested."""

src/lean_spec/subspecs/containers/exit/types.py

@@ -0,0 +1,15 @@
+"""Exit-specific SSZ types for the Lean Ethereum consensus specification."""
+
+from __future__ import annotations
+
+from lean_spec.types import SSZList
+
+from ...chain.config import VALIDATOR_REGISTRY_LIMIT
+from .exit import ValidatorExit
+
+
+class ValidatorExits(SSZList[ValidatorExit]):
+    """List of validator exit requests included in a block."""
+
+    ELEMENT_TYPE = ValidatorExit
+    LIMIT = int(VALIDATOR_REGISTRY_LIMIT)

src/lean_spec/subspecs/containers/state/__init__.py

@@ -2,18 +2,22 @@
 
 from .state import State
 from .types import (
+    ExitQueue,
     HistoricalBlockHashes,
     JustificationRoots,
     JustificationValidators,
     JustifiedSlots,
+    PendingDeposits,
     Validators,
 )
 
 __all__ = [
+    "ExitQueue",
     "HistoricalBlockHashes",
     "JustificationRoots",
     "JustificationValidators",
     "JustifiedSlots",
+    "PendingDeposits",
     "State",
     "Validators",
 ]