chore: replace "vote" jargon with "attestation" (#91)

* Use attestation jargon at `test_validator.py`

* Rename `latest_{known,new}_votes` into `latest_{known,new}_attestations`

* Rename `get_vote_target` into `get_attestation_target`

* Rename parameter `latest_votes` to `latest_attestations`

* Rename `accept_new_votes` to `accept_new_attestations`

* Fix comments on `store.py`

* Fix comments on `test_attestation_processing.py`

* Fix comments and variable names on `test_helper.py`

* Fix comments and variable names on `test_time_management.py`

* Fix comments and variable names on `test_fork_choice_algorithm.py`

* Fix comments on `block.py`

* Fix comments on `attestation.py`

* Fix comments and variable names on `state.py` and `test_state.py`

* Fix `CLAUDE.md`

* Fix documentation in `docs/client`

* Few more cleanups regarding "Voting"

* Run formatter

* Run formatter

* Fix comments from updated upstream

* Fix typos

Author: syjn99

CLAUDE.md

@@ -115,7 +115,7 @@ When creating SSZ types, follow these established patterns:
 ### Domain-Specific Types (Preferred)
 - Use meaningful names that describe the purpose: `JustificationValidators`, `HistoricalBlockHashes`, `Attestations`
 - Define domain-specific types in modular structure (see Architecture section below)
-- Avoid generic names with numbers like `Bitlist68719476736` or `SignedVoteList4096`
+- Avoid generic names with numbers like `Bitlist68719476736` or `SignedAttestationList4096`
 
 ### SSZType vs SSZModel Design Decision
 
@@ -168,16 +168,16 @@ class JustificationValidators(BaseBitlist):
 
 # In block/types.py
 class Attestations(SSZList):
-    """List of signed votes (attestations) included in a block."""
-    ELEMENT_TYPE = SignedVote
+    """List of signed attestations included in a block."""
+    ELEMENT_TYPE = SignedAttestation
     LIMIT = 4096  # VALIDATOR_REGISTRY_LIMIT
 ```
 
 **Avoid generic types:**
 ```python
 # Don't do this:
 class Bitlist68719476736(BaseBitlist): ...
-class SignedVoteList4096(SSZList): ...
+class SignedAttestationList4096(SSZList): ...
 ```
 
 ### API Compatibility

docs/client/chain.md

@@ -26,7 +26,7 @@ exist.
 ### Consensus Without Epochs
 
 Traditional beacon chain organizes time into epochs. Lean chain removes this.
-All validators vote in every slot. This simplifies the protocol significantly.
+All validators are expected to create, sign, and broadcast an attestation in every slot. This simplifies the protocol significantly.
 
 ### Signature Handling
 
@@ -37,9 +37,9 @@ are ready.
 Real signatures will be large, around 3-4 kilobytes each. Devnet 1 will test
 these.
 
-### Vote Processing
+### Attestation Processing
 
-Votes are collected and included in blocks without aggregation. Each vote is
+Attestations are collected and included in blocks without aggregation. Each attestation is
 separate. This is simpler than beacon chain aggregation.
 
 Later devnets will add aggregation to reduce bandwidth.
@@ -74,7 +74,7 @@ configuration.
 
 ## Chain Justification
 
-Blocks become justified when enough validators vote for them. Justification
+Blocks become justified when enough validators attestation for them. Justification
 happens when 2/3 of validators agree.
 
 Not every slot can be justified. Certain slots are special based on how far
@@ -85,7 +85,7 @@ justification from spreading too thin.
 ## Chain Finalization
 
 Finalization provides stronger guarantees than justification. A block is
-finalized when validators vote for it and there are no other justifiable
+finalized when validators attestation for it and there are no other justifiable
 positions between it and what they're voting for.
 
 Finalized blocks cannot be reverted. This provides economic certainty.
@@ -123,19 +123,19 @@ Blocks must pass several checks:
 - Proposer is correct for this slot
 - Parent reference is valid
 
-After these checks, the block is processed. Vote processing happens next.
+After these checks, the block is processed. Attestation processing happens next.
 
-## Vote Validation
+## Attestation Validation
 
-Each vote must meet requirements:
+Each attestation must meet requirements:
 
 - Source must be justified
 - Target must not already be justified
 - Block roots must be valid
 - Slot relationships must make sense
 - Target must be in a justifiable position
 
-Invalid votes are ignored. Valid votes are counted. When enough votes
+Invalid attestations are ignored. Valid attestations are counted. When enough attestations
 accumulate, justification happens.
 
 ## Justification Tracking

docs/client/forkchoice.md

@@ -18,9 +18,9 @@ consensus.
 ## How It Works
 
 The fork choice algorithm starts from the most recently justified block. It
-then follows validator votes forward through the tree of blocks.
+then follows validator attestations forward through the tree of blocks.
 
-At each branch point, the algorithm picks the child with the most votes. Votes
+At each branch point, the algorithm picks the child with the most attestations. Attestation
 for descendants count toward ancestors. This means voting for a block implicitly
 supports its entire history.
 
@@ -32,32 +32,32 @@ Only justified blocks can serve as fork choice starting points. This ties fork
 choice to finalization.
 
 Validators must justify new blocks before fork choice considers them. This
-creates a feedback loop: votes justify blocks, justified blocks anchor fork
+creates a feedback loop: attestations justify blocks, justified blocks anchor fork
 choice, fork choice determines what to build on.
 
-## Vote Timing
+## Attestation Timing
 
-Votes aren't processed immediately. The protocol divides each slot into
+Attestations aren't processed immediately. The protocol divides each slot into
 intervals. Different intervals have different roles:
 
-- Some intervals accept new votes
-- Some intervals update what's safe to vote for
+- Some intervals accept new attestations
+- Some intervals update what's safe to attestation for
 - Some intervals are for proposal
 
 This careful timing prevents certain attacks and ensures validators have
 consistent views.
 
 ## Safe Targets
 
-Validators need to know where they can safely vote. The safe target mechanism
+Validators need to know where they can safely submit an attestation. The safe target mechanism
 finds the latest block that has enough support.
 
-A block needs votes from 2/3 of validators to be safe. This threshold ensures
+A block needs attestations from 2/3 of validators to be safe. This threshold ensures
 that conflicting blocks can't both be safe simultaneously.
 
-## Computing Vote Targets
+## Computing Attestation Targets
 
-When a validator votes, it must choose a target carefully. The target should be
+When a validator creates an attestation, it must choose a target carefully. The target should be
 recent but not too recent. It should be safe but not too old.
 
 The algorithm starts from the current head and works backward. It moves back a
@@ -66,10 +66,10 @@ justified according to protocol rules.
 
 ## Handling New Information
 
-Fork choice must handle new blocks and new votes. When a block arrives, it gets
-added to the tree. Its votes are extracted and counted.
+Fork choice must handle new blocks and new attestations. When a block arrives, it gets
+added to the tree. Its attestations are extracted and counted.
 
-When a vote arrives over gossip, it's held temporarily. Votes are only counted
+When an attestation arrives over gossip, it's held temporarily. Attestations are only counted
 at specific times to maintain consistency.
 
 ## Genesis Initialization
@@ -82,7 +82,7 @@ slot.
 
 ## Reorganizations
 
-Sometimes fork choice changes. A new vote might tip the balance to a different
+Sometimes fork choice changes. A new attestation might tip the balance to a different
 fork. The head switches to the new fork.
 
 Reorganizations are normal in the protocol. Shallow reorgs happen occasionally.
@@ -91,7 +91,7 @@ Deep reorgs past finalization cannot happen if 2/3 of validators are honest.
 ## View Consistency
 
 Different validators may have different views temporarily. They might see
-blocks in different orders. They might receive votes at different times.
+blocks in different orders. They might receive attestations at different times.
 
 Fork choice rules ensure these differences don't break consensus. Eventually,
 all honest validators converge on the same head.
@@ -108,6 +108,6 @@ lost are discarded.
 ## Implementation Details
 
 The specification code implements these concepts precisely. It maintains the
-tree of blocks, tracks votes, and computes the head.
+tree of blocks, tracks attestations, and computes the head.
 
 This documentation explains the concepts. The code provides the exact algorithm.

docs/client/validator.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Validators participate in consensus by proposing blocks and voting. This
+Validators participate in consensus by proposing blocks and producing attestations. This
 document describes what honest validators do.
 
 ## Validator Assignment
@@ -29,17 +29,17 @@ This is deterministic. Everyone can compute who should propose at any slot.
 Proposers create blocks at the start of the slot. Specifically, in the first
 interval of the slot's four intervals.
 
-Early proposal gives other validators time to see and vote on the block.
+Early proposal gives other validators time to see and create an attestation on the block.
 
 ### Building a Block
 
 The proposer queries fork choice for the current head. This is the parent for
 the new block.
 
-The proposer collects recent votes. Valid votes get included in the block.
-A vote is valid if its source matches the current justified checkpoint.
+The proposer collects recent attestations. Valid attestations get included in the block.
+An attestation is valid if its source matches the current justified checkpoint.
 
-The proposer keeps adding votes until no more valid votes remain. This
+The proposer keeps adding attestations until no more valid attestations remain. This
 maximizes block utility.
 
 After building the block, the proposer computes the state root. This is the
@@ -50,14 +50,14 @@ state hash after applying the block.
 The proposer signs the block and broadcasts it to the network. Other validators
 receive and validate it.
 
-## Voting
+## Attesting
 
-Every validator votes in every slot. Voting happens in the second interval,
+Every validator attestations in every slot. Attesting happens in the second interval,
 after proposals are made.
 
-### What to Vote For
+### What to Attest For
 
-Validators vote for three things:
+Validators express their own views with an attestation, especially for three things:
 
 - The chain head
 - A target to justify
@@ -67,41 +67,41 @@ The head is what fork choice says is canonical. The target is computed based on
 safe blocks and justifiability rules. The source is the most recent justified
 checkpoint.
 
-### Why Vote
+### Why Attest
 
-Votes drive justification and finalization. When 2/3 of validators vote for the
+Attestations drive justification and finalization. When 2/3 of validators attestation for the
 same target, it becomes justified. Justification eventually leads to
 finalization.
 
-Votes also inform fork choice. Other validators see these votes and use them to
+Attestations also inform fork choice. Other validators see these attestations and use them to
 compute the head.
 
-### Broadcasting Votes
+### Broadcasting Attestations
 
-Validators sign their votes and broadcast them. The network uses a single topic
-for all votes. No subnets or committees in the current design.
+Validators sign their attestations and broadcast them. The network uses a single topic
+for all attestations. No subnets or committees in the current design.
 
 ## Timing
 
 The slot divides into four one-second intervals:
 
 - Interval 0: Proposals happen
-- Interval 1: Votes happen
+- Interval 1: Attestations happen
 - Interval 2: Safe targets update
 - Interval 3: More processing
 
 This rhythm keeps the network synchronized. Validators know when to expect
-blocks and votes.
+blocks and attestations.
 
 ## Aggregation
 
-Vote aggregation combines multiple votes into one. This saves bandwidth and
+Attestation aggregation combines multiple attestations into one. This saves bandwidth and
 block space.
 
-Devnet 0 has no aggregation. Each vote is separate. Future devnets will add
+Devnet 0 has no aggregation. Each attestation is separate. Future devnets will add
 aggregation.
 
-When aggregation is added, aggregators will collect votes and combine them.
+When aggregation is added, aggregators will collect attestations and combine them.
 Aggregated attestations will be broadcast separately.
 
 ## Signature Handling
@@ -119,7 +119,7 @@ Clients must implement the validator logic correctly. This includes:
 
 - Tracking which validators they control
 - Proposing when scheduled
-- Voting every slot
+- Producing an attestation every slot
 - Following fork choice
 - Obeying timing rules
 

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

@@ -38,7 +38,7 @@ class TickStep(BaseForkChoiceStep):
     Time advancement step.
 
     Advances the fork choice store time to a specific unix timestamp.
-    This triggers interval-based actions like vote processing.
+    This triggers interval-based actions like attestation processing.
     """
 
     step_type: Literal["tick"] = "tick"
@@ -114,8 +114,8 @@ class AttestationStep(BaseForkChoiceStep):
     """
     Attestation processing step.
 
-    Processes an attestation (signed vote) received from gossip.
-    This updates validator vote tracking in the store.
+    Processes an attestation received from gossip.
+    This updates validator attestation tracking in the store.
 
     Note: Attestations included in blocks are processed automatically
     when the block is processed. This step is for gossip attestations.

src/lean_spec/subspecs/containers/attestation/attestation.py

@@ -42,7 +42,7 @@ class Attestation(Container):
     """The index of the validator making the attestation."""
 
     data: AttestationData
-    """The attestation data voted on by the validator."""
+    """The attestation data produced by the validator."""
 
 
 class SignedAttestation(Container):
@@ -62,9 +62,9 @@ class AggregatedAttestations(Container):
     """Bitfield indicating which validators participated in the aggregation."""
 
     data: AttestationData
-    """Combined vote data similar to the beacon chain format.
+    """Combined attestation data similar to the beacon chain format.
 
-    Multiple validator votes are aggregated here without the complexity of
+    Multiple validator attestations are aggregated here without the complexity of
     committee assignments.
     """
 
@@ -73,10 +73,10 @@ class SignedAggregatedAttestations(Container):
     """Aggregated attestation bundled with aggregated signatures."""
 
     message: AggregatedAttestations
-    """Aggregated vote data."""
+    """Aggregated attestation data."""
 
     signature: AggregatedSignatures
-    """Aggregated vote plus its combined signature.
+    """Aggregated attestation plus its combined signature.
 
     Stores a naive list of validator signatures that mirrors the attestation
     order.

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

@@ -21,15 +21,15 @@ class BlockBody(Container):
     """
     The body of a block, containing payload data.
 
-    Currently, the main operation is voting. Validators submit votes which are
+    Currently, the main operation is voting. Validators submit attestations which are
     packaged into blocks.
     """
 
     attestations: Attestations
     """Plain validator attestations carried in the block body.
 
     Individual signatures live in the aggregated block signature list, so
-    these entries contain only vote data without per-attestation signatures.
+    these entries contain only attestation data without per-attestation signatures.
     """
 
 
@@ -87,14 +87,14 @@ class BlockWithAttestation(Container):
     """The proposed block message."""
 
     proposer_attestation: Attestation
-    """The proposer's vote corresponding to this block."""
+    """The proposer's attestation corresponding to this block."""
 
 
 class SignedBlockWithAttestation(Container):
-    """Envelope carrying a block, proposer vote, and aggregated signatures."""
+    """Envelope carrying a block, an attestation from proposer, and aggregated signatures."""
 
     message: BlockWithAttestation
-    """The block plus proposer vote being signed."""
+    """The block plus an attestation from proposer being signed."""
 
     signature: BlockSignatures
     """Aggregated signature payload for the block.