pqdevnet0: container specs

pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
 requires-python = ">=3.12"
 dependencies = [
     "pydantic>=2.9.2,<3",
+    "remerkleable>=0.1.28,<0.2",
     "typing-extensions>=4.4",
 ]
 

src/lean_spec/subspecs/pqdevnet-0/__init__.py

@@ -0,0 +1 @@
+"""Specification for pqdevnet-0"""

src/lean_spec/subspecs/pqdevnet-0/block.py

@@ -0,0 +1,27 @@
+"""
+A `Block` is a single link in the Lean Consensus chain. Each `Block` contains
+associated metadata like the slot number, parent block hash and votes.
+
+Together, these blocks form a cryptographically secure journal recording the
+history of all state transitions that have happened since the genesis of the
+chain.
+"""
+
+from dataclasses import dataclass
+from remerkleable.basic import uint64
+from remerkleable.byte_arrays import Bytes32
+from remerkleable.complex import List
+from pydantic import BaseModel, ConfigDict
+
+from preset import VALIDATOR_REGISTRY_LIMIT
+from vote import Vote
+
+@dataclass
+class Block(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    slot: uint64
+    parent: Bytes32
+    votes: List[Vote, VALIDATOR_REGISTRY_LIMIT]
+    # Diverged from 3SF-mini.py: Removed Optional from `state_root`
+    state_root: Bytes32

src/lean_spec/subspecs/pqdevnet-0/preset.py

@@ -0,0 +1,26 @@
+"""
+The `preset` module contains the parameters that are used to configure the
+Lean Consensus chain.
+"""
+
+from remerkleable.basic import uint64
+
+# Time parameters
+# ---------------------------------------------------------------
+
+# 4 seconds
+SLOT_DURATION_MS = 4000
+
+# Basis points (out of 10000)
+PROPOSER_REORG_CUTOFF_BPS: 2500
+VOTE_DUE_BPS: 5000
+FAST_CONFIRM_DUE_BPS: 7500
+VIEW_FREEZE_CUTOFF_BPS: 7500
+
+# Misc
+# ---------------------------------------------------------------
+
+# 2^18, enough for 2^18 / (60 / 4) / 60 / 24 = 12.1 days
+MAX_HISTORICAL_BLOCK_HASHES: uint64 = 262144
+
+VALIDATOR_REGISTRY_LIMIT: uint64 = 4096

src/lean_spec/subspecs/pqdevnet-0/state.py

@@ -0,0 +1,40 @@
+"""
+A `State` is a collection of metadata that describes the current state of the
+Lean Consensus chain. It contains information about the latest justified and
+finalized blocks, as well as the historical block hashes and justified slots.
+
+It is used to verify the integrity of the chain and to ensure that the chain is
+progressing correctly.
+"""
+
+from dataclasses import dataclass
+from remerkleable.basic import uint64
+from remerkleable.bitfields import Bitlist
+from remerkleable.byte_arrays import Bytes32
+from remerkleable.complex import List
+from pydantic import BaseModel, ConfigDict
+
+from preset import MAX_HISTORICAL_BLOCK_HASHES, VALIDATOR_REGISTRY_LIMIT
+
+@dataclass
+class State(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    # Diverged from 3SF-mini.py:
+    #   - Removed `config: Config` from the state
+    #   - Using uint64 instead of native int for all fields
+    #   - Using Bytes32 instead of native str for all fields
+
+    latest_justified_hash: Bytes32
+    latest_justified_slot: uint64
+
+    latest_finalized_hash: Bytes32
+    latest_finalized_slot: uint64
+
+    historical_block_hashes: List[Bytes32, MAX_HISTORICAL_BLOCK_HASHES]
+    justified_slots: List[bool, MAX_HISTORICAL_BLOCK_HASHES]
+
+    # Diverged from 3SF-mini.py:
+    #   - Flattened `justifications: Dict[str, List[bool]]` for SSZ compatibility
+    justifications_roots: List[Bytes32, MAX_HISTORICAL_BLOCK_HASHES]
+    justifications_validators: Bitlist[MAX_HISTORICAL_BLOCK_HASHES * VALIDATOR_REGISTRY_LIMIT]

src/lean_spec/subspecs/pqdevnet-0/vote.py

@@ -0,0 +1,27 @@
+"""
+A `Vote` is a single vote for a block in the Lean Consensus chain. Each `Vote`
+contains information about the validator that voted, the slot of the block they
+voted for, and the block hash they voted for.
+"""
+
+from dataclasses import dataclass
+from remerkleable.basic import uint64
+from remerkleable.byte_arrays import Bytes32
+from pydantic import BaseModel, ConfigDict
+
+@dataclass
+class Vote(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    # Diverged from 3SF-mini.py:
+    #   - Using `uint64` instead of native `int` for all fields
+    #   - Using `Bytes32` instead of native `str` for all fields
+
+    validator_id: uint64
+    slot: uint64
+    head: Bytes32
+    head_slot: uint64
+    target: Bytes32
+    target_slot: uint64
+    source: Bytes32
+    source_slot: uint64