docs: update docs

Author: unnawut

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

@@ -100,12 +100,13 @@ class BlockSpec(CamelModel):
 
     valid_signature: bool = True
     """
-    If False, the proposer attestation will be given a dummy/invalid signature.
+    Flag whether the proposer's signature in generated block should be valid.
 
     Used for testing that verification properly rejects invalid block signatures.
     When False, a structurally valid but cryptographically invalid signature
     (all zeros) will be generated for the proposer attestation instead of a
     proper XMSS signature.
 
-    Default is True (valid signatures).
+    Defaults to True (valid signature).
+    If False, the proposer attestation will be given a dummy/invalid signature.
     """

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

@@ -38,9 +38,12 @@ class SignedAttestationSpec(CamelModel):
 
     valid_signature: bool = True
     """
-    If False, this attestation will be given a dummy/invalid signature.
+    Flag whether the generated attestation signature should be valid.
 
-    Used for testing that verification properly rejects invalid signatures.
+    Used for testing that verification properly rejects invalid attestation signatures.
     When False, a structurally valid but cryptographically invalid signature
-    (all zeros) will be generated instead of a proper XMSS signature.
+    (all zeros) will be generated for the attestation instead of a proper XMSS signature.
+
+    Defaults to True (valid signature).
+    If False, the attestation will be given a dummy/invalid signature.
     """

src/lean_spec/subspecs/koalabear/field.py

@@ -105,29 +105,28 @@ def __get_pydantic_core_schema__(
         cls, source_type: Any, handler: GetCoreSchemaHandler
     ) -> core_schema.CoreSchema:
         """
-        Hook into Pydantic's validation system.
+        Hook into Pydantic's validation system for strict field element validation.
 
-        This schema defines how to handle the Fp field element type:
-        1. If the input is already an Fp instance, accept it.
-        2. Otherwise, validate the input as an integer within [0, P)
-            and then instantiate Fp.
-        3. For serialization (e.g., to JSON), convert to a plain int.
+        This schema ensures that only values in the range [0, P) are accepted
+        during Pydantic model validation.
         """
         # Validator that takes an integer and returns an Fp instance
         from_int_validator = core_schema.no_info_plain_validator_function(cls)
 
-        # Schema that first validates the input as an int, then calls our validator
+        # Schema that first validates the input as an int in the range [0, P),
+        # then calls our validator
         python_schema = core_schema.chain_schema(
             [core_schema.int_schema(ge=0, lt=P, strict=True), from_int_validator]
         )
 
         return core_schema.union_schema(
             [
-                # Case 1: The value is already the correct type
+                # Case 1: The value is already our field element type
                 core_schema.is_instance_schema(cls),
-                # Case 2: The value needs to be parsed and validated
+                # Case 2: The value is a standard int and needs to be parsed and validated
                 python_schema,
             ],
+            # For serialization (e.g., to JSON), convert the instance back to a plain int.
             serialization=core_schema.plain_serializer_function_ser_schema(
                 lambda x: x.value, return_schema=core_schema.int_schema()
             ),

tests/consensus/devnet/verify_signature/test_basic_signature.py

@@ -0,0 +1,96 @@
+"""Invalid signature verification tests"""
+
+import pytest
+from consensus_testing import (
+    BlockSpec,
+    VerifySignatureTestFiller,
+    SignedAttestationSpec,
+    generate_pre_state,
+)
+
+from lean_spec.subspecs.containers.slot import Slot
+from lean_spec.types import Uint64
+
+pytestmark = pytest.mark.valid_until("Devnet")
+
+
+def test_invalid_signature(
+    verify_signature_test: VerifySignatureTestFiller,
+) -> None:
+    """
+    Test that invalid signatures are properly rejected during verification.
+
+    Scenario
+    --------
+    - Single block at slot 1
+    - Proposer attestation has an invalid signature
+    - No additional attestations (only proposer attestation)
+
+    Expected Behavior
+    -----------------
+    1. Proposer's signature in SignedBlockWithAttestation is rejected
+
+    Why This Matters
+    ----------------
+    This test verifies the negative case:
+    - Signature verification actually validates cryptographic correctness
+      not just structural correctness.
+    - Invalid signatures are caught, not silently accepted
+    """
+    verify_signature_test(
+        anchor_state=generate_pre_state(num_validators=1),
+        block=BlockSpec(
+            slot=Slot(1),
+            attestations=[],
+            valid_signature=False,
+        ),
+        expect_exception=AssertionError,
+    )
+
+def test_mixed_valid_invalid_signatures(
+    verify_signature_test: VerifySignatureTestFiller,
+) -> None:
+    """
+    Test that signature verification catches invalid signatures among valid ones.
+
+    Scenario
+    --------
+    - Single block at slot 1
+    - Proposer attestation from validator 1
+    - 2 non-proposer attestations from validators 0 and 2
+    - Total: 3 signatures, middle attestation (validator 2) has an invalid signature
+
+    Expected Behavior
+    -----------------
+    1. The SignedBlockWithAttestation is rejected due to 1 invalid signature
+
+    Why This Matters
+    ----------------
+    This test verifies that signature verification:
+    - Checks every signature individually, not just the first or last
+    - Cannot be bypassed by surrounding invalid signatures with valid ones
+    - Properly fails even when some signatures are valid
+    - Validates all attestations in the block
+    """
+    verify_signature_test(
+        anchor_state=generate_pre_state(num_validators=3),
+        block=BlockSpec(
+            slot=Slot(1),
+            attestations=[
+                SignedAttestationSpec(
+                    validator_id=Uint64(0),
+                    slot=Slot(1),
+                    target_slot=Slot(0),
+                    target_root_label="genesis",
+                ),
+                SignedAttestationSpec(
+                    validator_id=Uint64(2),
+                    slot=Slot(1),
+                    target_slot=Slot(0),
+                    target_root_label="genesis",
+                    valid_signature=False,
+                ),
+            ],
+        ),
+        expect_exception=AssertionError,
+    )