networking: add subspec scaffolding (leanEthereum#20)

* networking: add subspec scaffolding

* use Checkpoint in Status

Author: tcoratger

src/lean_spec/subspecs/chain/config.py

@@ -15,6 +15,12 @@
 SLOT_DURATION_MS: Final = 4000
 """The fixed duration of a single slot in milliseconds."""
 
+SECONDS_PER_SLOT: Final = SLOT_DURATION_MS // 1000
+"""The fixed duration of a single slot in seconds."""
+
+SLOTS_PER_EPOCH: Final = 96
+"""The number of slots in an epoch."""
+
 PROPOSER_REORG_CUTOFF_BPS: Final = 2500
 """
 The deadline within a slot (in basis points) for a proposer to publish a
@@ -74,6 +80,8 @@ class _ChainConfig(BaseModel):
 
     # Time Parameters
     slot_duration_ms: Uint64
+    second_per_slot: Uint64
+    slots_per_epoch: Uint64
     proposer_reorg_cutoff_bps: BasisPoint
     vote_due_bps: BasisPoint
     fast_confirm_due_bps: BasisPoint
@@ -87,6 +95,8 @@ class _ChainConfig(BaseModel):
 # The Devnet Chain Configuration.
 DEVNET_CONFIG: Final = _ChainConfig(
     slot_duration_ms=SLOT_DURATION_MS,
+    second_per_slot=SECONDS_PER_SLOT,
+    slots_per_epoch=SLOTS_PER_EPOCH,
     proposer_reorg_cutoff_bps=PROPOSER_REORG_CUTOFF_BPS,
     vote_due_bps=VOTE_DUE_BPS,
     fast_confirm_due_bps=FAST_CONFIRM_DUE_BPS,

src/lean_spec/subspecs/networking/__init__.py

@@ -0,0 +1,30 @@
+"""Exports the networking subspec components."""
+
+from .config import (
+    MAX_REQUEST_BLOCKS,
+    MESSAGE_DOMAIN_INVALID_SNAPPY,
+    MESSAGE_DOMAIN_VALID_SNAPPY,
+)
+from .gossipsub import GossipsubParameters
+from .messages import (
+    BLOCKS_BY_ROOT_PROTOCOL_V1,
+    STATUS_PROTOCOL_V1,
+    BlocksByRootRequest,
+    BlocksByRootResponse,
+    Status,
+)
+from .types import DomainType, ProtocolId
+
+__all__ = [
+    "MAX_REQUEST_BLOCKS",
+    "MESSAGE_DOMAIN_INVALID_SNAPPY",
+    "MESSAGE_DOMAIN_VALID_SNAPPY",
+    "GossipsubParameters",
+    "BLOCKS_BY_ROOT_PROTOCOL_V1",
+    "STATUS_PROTOCOL_V1",
+    "BlocksByRootRequest",
+    "BlocksByRootResponse",
+    "Status",
+    "DomainType",
+    "ProtocolId",
+]

src/lean_spec/subspecs/networking/config.py

@@ -0,0 +1,14 @@
+"""Networking Configuration Constants."""
+
+from typing_extensions import Final
+
+from .types import DomainType
+
+MAX_REQUEST_BLOCKS: Final = 2**10
+"""Maximum number of blocks in a single request."""
+
+MESSAGE_DOMAIN_INVALID_SNAPPY: Final = DomainType(b"\x00\x00\x00\x00")
+"""4-byte domain for gossip message-id isolation of invalid snappy messages."""
+
+MESSAGE_DOMAIN_VALID_SNAPPY: Final = DomainType(b"\x01\x00\x00\x00")
+"""4-byte domain for gossip message-id isolation of valid snappy messages."""

src/lean_spec/subspecs/networking/gossipsub.py

@@ -0,0 +1,48 @@
+"""Gossipsub protocol parameters."""
+
+from lean_spec.subspecs.chain.config import DEVNET_CONFIG
+from lean_spec.types import StrictBaseModel
+
+
+class GossipsubParameters(StrictBaseModel):
+    """A model holding the canonical gossipsub parameters."""
+
+    protocol_id: str = "/meshsub/1.0.0"
+    """The protocol ID for gossip messages."""
+
+    d: int = 8
+    """The target number of peers for a stable gossip mesh topic."""
+
+    d_low: int = 6
+    """
+    The low watermark for the number of peers in a stable gossip mesh topic.
+    """
+
+    d_high: int = 12
+    """
+    The high watermark for the number of peers in a stable gossip mesh topic.
+    """
+
+    d_lazy: int = 6
+    """The target number of peers for gossip-only connections."""
+
+    heartbeat_interval_secs: float = 0.7
+    """The frequency of the gossipsub heartbeat in seconds."""
+
+    fanout_ttl_secs: int = 60
+    """The time-to-live for fanout maps in seconds."""
+
+    mcache_len: int = 6
+    """The number of history windows to retain full messages in the cache."""
+
+    mcache_gossip: int = 3
+    """The number of history windows to gossip about."""
+
+    seen_ttl_secs: int = (
+        DEVNET_CONFIG.second_per_slot * DEVNET_CONFIG.slots_per_epoch * 2
+    )
+    """
+    The expiry time in seconds for the cache of seen message IDs.
+
+    This is calculated as SECONDS_PER_SLOT * SLOTS_PER_EPOCH * 2.
+    """

src/lean_spec/subspecs/networking/messages.py

@@ -0,0 +1,64 @@
+"""
+Request/Response Domain Message Types.
+
+This module defines the data structures for the peer-to-peer request/response
+domain. All messages are SSZ-encoded and then compressed with Snappy frames.
+"""
+
+from pydantic import Field
+from typing_extensions import Annotated
+
+from lean_spec.subspecs.containers import Checkpoint, SignedBlock
+from lean_spec.types import Bytes32, StrictBaseModel
+
+from .config import MAX_REQUEST_BLOCKS
+from .types import ProtocolId
+
+# --- Status v1 ---
+
+STATUS_PROTOCOL_V1: ProtocolId = "/leanconsensus/req/status/1/"
+"""The protocol ID for the Status v1 request/response message."""
+
+
+class Status(StrictBaseModel):
+    """
+    The Status message, used by clients to share their chain state.
+
+    This is the first message sent upon a new connection and is essential for
+    the peer-to-peer handshake. It allows nodes to verify compatibility and
+    determine if they are on the same chain.
+    """
+
+    finalized: Checkpoint
+    """The client's latest finalized checkpoint."""
+
+    head: Checkpoint
+    """The client's current head checkpoint."""
+
+
+# --- BlocksByRoot v1 ---
+
+BLOCKS_BY_ROOT_PROTOCOL_V1: ProtocolId = "/leanconsensus/req/blocks_by_root/1/"
+"""The protocol ID for the BlocksByRoot v1 request/response message."""
+
+BlocksByRootRequest = Annotated[
+    list[Bytes32],
+    Field(max_length=MAX_REQUEST_BLOCKS),
+]
+"""
+A request for one or more blocks by their root hashes.
+
+This is primarily used to recover recent or missing blocks from a peer.
+"""
+
+BlocksByRootResponse = Annotated[
+    list[SignedBlock],
+    Field(max_length=MAX_REQUEST_BLOCKS),
+]
+"""
+A response containing the requested `SignedBlock` objects.
+
+The length of the list may be less than the number of requested blocks if
+the responding peer does not have all of them. Each block is sent in a
+separate `response_chunk`.
+"""

src/lean_spec/subspecs/networking/types.py

@@ -0,0 +1,11 @@
+"""Networking-related type definitions for the specification."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+DomainType = Annotated[bytes, Field(min_length=4, max_length=4)]
+"""A 4-byte value used for domain separation in message-ids."""
+
+ProtocolId = str
+"""A string representing a libp2p protocol ID."""