chore: remove containers markdown docs (#89)

* chore: remove unused client yaml files

* chore: move containers markdown docs to doc comments

Author: unnawut

docs/client/containers.md

@@ -1,4 +1,12 @@
-"""The container types for the Lean consensus specification."""
+"""
+The container types for the Lean consensus specification.
+
+All containers use SSZ encoding. SSZ provides deterministic serialization and
+efficient merkleization.
+
+Hash functions used for merkleization differ by devnet. Early devnets use
+SHA256. Later devnets will switch to Poseidon2 for better SNARK compatibility.
+"""
 
 from .attestation import (
     AggregatedAttestations,

src/lean_spec/client/nodes.yaml

@@ -1,4 +1,16 @@
-"""Attestation-related container definitions."""
+"""
+Attestation-related container definitions.
+
+Attestations are how validators express their view of the chain.
+Each attestation specifies:
+
+- What the validator thinks is the chain head
+- What is already justified (source)
+- What should be justified next (target)
+
+Attestations can be aggregated to save space, but the current specification
+doesn't do this yet.
+"""
 
 from lean_spec.subspecs.containers.slot import Slot
 from lean_spec.types import Bytes4000, Container, Uint64

src/lean_spec/client/validators.yaml

@@ -1,4 +1,13 @@
-"""Block Containers for the Lean Ethereum consensus specification."""
+"""
+Block Containers for the Lean Ethereum consensus specification.
+
+A block proposes changes to the chain. It references its parent block, creating
+a chain. The block includes a state root that represents the result of
+applying this block.
+
+Each block has a proposer who created it. The slot determines which validator
+can propose.
+"""
 
 from lean_spec.subspecs.containers.slot import Slot
 from lean_spec.types import Bytes32, Uint64
@@ -9,7 +18,12 @@
 
 
 class BlockBody(Container):
-    """The body of a block, containing payload data."""
+    """
+    The body of a block, containing payload data.
+
+    Currently, the main operation is voting. Validators submit votes which are
+    packaged into blocks.
+    """
 
     attestations: Attestations
     """Plain validator attestations carried in the block body.
@@ -20,7 +34,16 @@ class BlockBody(Container):
 
 
 class BlockHeader(Container):
-    """The header of a block, containing metadata."""
+    """
+    The header of a block, containing metadata.
+
+    Block headers summarize blocks without storing full content. The header
+    includes references to the parent and the resulting state. It also contains
+    a hash of the block body.
+
+    Headers are smaller than full blocks. They're useful for tracking the chain
+    without storing everything.
+    """
 
     slot: Slot
     """The slot in which the block was proposed."""

src/lean_spec/subspecs/containers/__init__.py

@@ -1,4 +1,10 @@
-"""Checkpoint Container."""
+"""
+Checkpoint Container.
+
+A checkpoint marks a specific moment in the chain. It combines a block
+identifier with a slot number. Checkpoints are used for justification and
+finalization.
+"""
 
 from typing import Self
 

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

@@ -1,4 +1,10 @@
-"""State Container for the Lean Ethereum consensus specification."""
+"""
+State Container for the Lean Ethereum consensus specification.
+
+The state contains everything needed for consensus. It tracks the current slot,
+recent blocks, and validator votes. State also records which blocks are
+justified and finalized.
+"""
 
 from typing import Any, Dict, List