refactor(lstar): freeze constructed-once SSZ containers (leanEthereum#842)

Set frozen=True on the lstar containers that are built once and never
mutated after construction: GenesisConfig, Validator, AggregatedAttestation,
and SignedAggregatedAttestation. This completes the freeze begun on
Checkpoint, AttestationData, Attestation, SingleMessageAggregate, and
MultiMessageAggregate, so accidental post-construction mutation now raises
instead of silently succeeding.

Freezing Validator required one call-site change: the fork-choice test
fixture injected public keys by mutating each validator in place. It now
rebuilds each validator with model_copy(update=...), which is byte-identical
in hash_tree_root and leaves the originals untouched.

Block, BlockHeader, BlockBody, and SignedBlock stay mutable for now. Their
state_root and body are patched in place during block production and the
state transition (block_production.py and state_transition.py), a two-pass
pattern entangled with the larger state-transition refactor. State and Store
remain mutable by design.

Frozen is an enforcement aid, not a hard immutability guarantee: model_config
is itself a mutable dict and an unfreeze-then-assign sequence can still leave
a field mutable (pydantic#12361). It catches accidental mutation; it is not a
soundness boundary.

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

Author: alexanderlhicks

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

@@ -229,9 +229,14 @@ def make_fixture(self) -> Self:
         for i, validator in enumerate(self.anchor_state.validators):
             index = ValidatorIndex(i)
             attestation_public_key, proposal_public_key = key_manager.get_public_keys(index)
-            validator.attestation_public_key = attestation_public_key.encode_bytes()
-            validator.proposal_public_key = proposal_public_key.encode_bytes()
-            updated_validators.append(validator)
+            updated_validators.append(
+                validator.model_copy(
+                    update={
+                        "attestation_public_key": attestation_public_key.encode_bytes(),
+                        "proposal_public_key": proposal_public_key.encode_bytes(),
+                    }
+                )
+            )
 
         # Updating validators changes the state root.
         # We must also update the anchor block to match.

src/lean_spec/spec/forks/lstar/containers/attestation.py

@@ -31,6 +31,8 @@ class SignedAttestation(Attestation):
 class AggregatedAttestation(Container):
     """Aggregated attestation consisting of participation bits and message."""
 
+    model_config = Container.model_config | {"frozen": True}
+
     aggregation_bits: AggregationBits
     """Bitfield indicating which validators participated in the aggregation."""
 
@@ -49,6 +51,8 @@ class SignedAggregatedAttestation(Container):
     Contains the attestation data and the aggregated signature proof.
     """
 
+    model_config = Container.model_config | {"frozen": True}
+
     data: AttestationData
     """Combined attestation data similar to the beacon chain format."""
 

src/lean_spec/spec/forks/lstar/containers/validator.py

@@ -14,13 +14,17 @@ class GenesisConfig(Container):
     in the absence of more complex mechanisms like RANDAO or deposits.
     """
 
+    model_config = Container.model_config | {"frozen": True}
+
     genesis_time: Uint64
     """The timestamp of the genesis block."""
 
 
 class Validator(Container):
     """Represents a validator's static metadata and operational interface."""
 
+    model_config = Container.model_config | {"frozen": True}
+
     attestation_public_key: Bytes52
     """XMSS public key for signing attestations."""
 

tests/lean_spec/spec/forks/lstar/containers/test_attestation.py

@@ -1,5 +1,8 @@
 """Tests for AggregatedAttestation structure."""
 
+import pytest
+from pydantic import ValidationError
+
 from lean_spec.spec.forks import (
     AggregationBits,
     Checkpoint,
@@ -10,8 +13,10 @@
 from lean_spec.spec.forks.lstar.containers import (
     AggregatedAttestation,
     AttestationData,
+    SignedAggregatedAttestation,
+    SingleMessageAggregate,
 )
-from lean_spec.spec.ssz import Bytes32
+from lean_spec.spec.ssz import ByteList512KiB, Bytes32
 
 
 class TestAggregatedAttestation:
@@ -51,3 +56,55 @@ def test_aggregated_attestation_with_many_validators(self) -> None:
 
         recovered = aggregate.aggregation_bits.to_validator_indices()
         assert recovered == validator_indices
+
+
+class TestAggregatedAttestationImmutability:
+    """Frozen-model semantics forbid post-construction mutation."""
+
+    def test_assigning_data_raises(self) -> None:
+        """Assigning new data on a constructed aggregated attestation raises."""
+        attestation_data = AttestationData(
+            slot=Slot(5),
+            head=Checkpoint(root=Bytes32.zero(), slot=Slot(4)),
+            target=Checkpoint(root=Bytes32.zero(), slot=Slot(3)),
+            source=Checkpoint(root=Bytes32.zero(), slot=Slot(2)),
+        )
+        aggregate = AggregatedAttestation(
+            aggregation_bits=AggregationBits.from_indices([ValidatorIndex(1)]),
+            data=attestation_data,
+        )
+        with pytest.raises(ValidationError, match="frozen"):
+            aggregate.data = attestation_data
+
+    def test_assigning_aggregation_bits_raises(self) -> None:
+        """Assigning new bits on a constructed aggregated attestation raises."""
+        attestation_data = AttestationData(
+            slot=Slot(5),
+            head=Checkpoint(root=Bytes32.zero(), slot=Slot(4)),
+            target=Checkpoint(root=Bytes32.zero(), slot=Slot(3)),
+            source=Checkpoint(root=Bytes32.zero(), slot=Slot(2)),
+        )
+        bits = AggregationBits.from_indices([ValidatorIndex(1)])
+        aggregate = AggregatedAttestation(aggregation_bits=bits, data=attestation_data)
+        with pytest.raises(ValidationError, match="frozen"):
+            aggregate.aggregation_bits = bits
+
+
+class TestSignedAggregatedAttestationImmutability:
+    """Frozen-model semantics forbid post-construction mutation."""
+
+    def test_assigning_proof_raises(self) -> None:
+        """Assigning a new proof on a constructed signed aggregated attestation raises."""
+        attestation_data = AttestationData(
+            slot=Slot(5),
+            head=Checkpoint(root=Bytes32.zero(), slot=Slot(4)),
+            target=Checkpoint(root=Bytes32.zero(), slot=Slot(3)),
+            source=Checkpoint(root=Bytes32.zero(), slot=Slot(2)),
+        )
+        proof = SingleMessageAggregate(
+            participants=AggregationBits.from_indices([ValidatorIndex(1)]),
+            proof=ByteList512KiB(data=b""),
+        )
+        signed = SignedAggregatedAttestation(data=attestation_data, proof=proof)
+        with pytest.raises(ValidationError, match="frozen"):
+            signed.proof = proof

tests/lean_spec/spec/forks/lstar/containers/test_validator.py

@@ -0,0 +1,39 @@
+"""Tests for the GenesisConfig and Validator containers."""
+
+import pytest
+from pydantic import ValidationError
+
+from lean_spec.spec.forks.lstar.containers import GenesisConfig, Validator
+from lean_spec.spec.ssz import Bytes52, Uint64
+
+
+class TestGenesisConfigImmutability:
+    """Frozen-model semantics forbid post-construction mutation."""
+
+    def test_assigning_genesis_time_raises(self) -> None:
+        """Assigning a new genesis time on a constructed config raises."""
+        config = GenesisConfig(genesis_time=Uint64(1_700_000_000))
+        with pytest.raises(ValidationError, match="frozen"):
+            config.genesis_time = Uint64(1_700_000_001)
+
+
+class TestValidatorImmutability:
+    """Frozen-model semantics forbid post-construction mutation."""
+
+    def test_assigning_attestation_public_key_raises(self) -> None:
+        """Assigning a new attestation key on a constructed validator raises."""
+        validator = Validator(
+            attestation_public_key=Bytes52.zero(),
+            proposal_public_key=Bytes52.zero(),
+        )
+        with pytest.raises(ValidationError, match="frozen"):
+            validator.attestation_public_key = Bytes52(b"\xff" * 52)
+
+    def test_assigning_proposal_public_key_raises(self) -> None:
+        """Assigning a new proposal key on a constructed validator raises."""
+        validator = Validator(
+            attestation_public_key=Bytes52.zero(),
+            proposal_public_key=Bytes52.zero(),
+        )
+        with pytest.raises(ValidationError, match="frozen"):
+            validator.proposal_public_key = Bytes52(b"\xff" * 52)