csm-dashboard 0.2.0__py3-none-any.whl

src/core/types.py

@@ -0,0 +1,153 @@
+"""Data models for CSM Dashboard."""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ..data.beacon import ValidatorInfo
+
+
+class NodeOperator(BaseModel):
+    """Node operator data from CSModule contract."""
+
+    node_operator_id: int
+    total_added_keys: int
+    total_withdrawn_keys: int
+    total_deposited_keys: int
+    total_vetted_keys: int
+    stuck_validators_count: int
+    depositable_validators_count: int
+    target_limit: int
+    target_limit_mode: int
+    total_exited_keys: int
+    enqueued_count: int
+    manager_address: str
+    proposed_manager_address: str
+    reward_address: str
+    proposed_reward_address: str
+    extended_manager_permissions: bool
+
+
+class BondSummary(BaseModel):
+    """Bond information for an operator."""
+
+    current_bond_wei: int
+    required_bond_wei: int
+    current_bond_eth: Decimal
+    required_bond_eth: Decimal
+    excess_bond_eth: Decimal
+
+
+class RewardsInfo(BaseModel):
+    """Rewards data from merkle tree."""
+
+    cumulative_fee_shares: int
+    proof: list[str]
+
+
+class APYMetrics(BaseModel):
+    """APY calculations for an operator.
+
+    Note: Validator APY (consensus rewards) is NOT included because CSM operators
+    don't receive those rewards directly - they go to Lido protocol and are
+    redistributed via CSM reward distributions (captured in reward_apy).
+
+    Historical APY is calculated from actual distributed rewards in IPFS logs,
+    which is more accurate than calculating from unclaimed amounts.
+    """
+
+    # Historical Reward APY (from IPFS distribution logs) - most accurate
+    historical_reward_apy_28d: float | None = None  # Last ~28 days (1 frame)
+    historical_reward_apy_ltd: float | None = None  # Lifetime
+
+    # Bond APY (stETH rebase appreciation)
+    bond_apy: float | None = None
+
+    # Net APY (Historical Reward APY + Bond APY)
+    net_apy_28d: float | None = None
+    net_apy_ltd: float | None = None
+
+    # Legacy fields (deprecated, kept for backwards compatibility)
+    reward_apy_7d: float | None = None
+    reward_apy_28d: float | None = None
+    net_apy_7d: float | None = None
+
+
+class StrikeSummary(BaseModel):
+    """Summary of strikes for an operator."""
+
+    total_validators_with_strikes: int = 0
+    validators_at_risk: int = 0  # Validators with 3+ strikes (ejection eligible)
+    validators_near_ejection: int = 0  # Validators with 2 strikes (one away from ejection)
+    total_strikes: int = 0
+    max_strikes: int = 0  # Highest strike count on any single validator
+
+
+class HealthStatus(BaseModel):
+    """Overall health status for an operator."""
+
+    bond_healthy: bool = True
+    bond_deficit_eth: Decimal = Decimal(0)
+    stuck_validators_count: int = 0
+    slashed_validators_count: int = 0
+    validators_at_risk_count: int = 0  # Validators with balance < 32 ETH
+    strikes: StrikeSummary = StrikeSummary()
+
+    @property
+    def has_issues(self) -> bool:
+        """Check if there are any health issues."""
+        return (
+            not self.bond_healthy
+            or self.stuck_validators_count > 0
+            or self.slashed_validators_count > 0
+            or self.validators_at_risk_count > 0
+            or self.strikes.total_validators_with_strikes > 0  # Any strikes = warning
+        )
+
+
+class OperatorRewards(BaseModel):
+    """Complete rewards summary for display."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    node_operator_id: int
+    manager_address: str
+    reward_address: str
+
+    # Bond information
+    current_bond_eth: Decimal
+    required_bond_eth: Decimal
+    excess_bond_eth: Decimal
+
+    # Rewards information
+    cumulative_rewards_shares: int
+    cumulative_rewards_eth: Decimal
+    distributed_shares: int
+    distributed_eth: Decimal
+    unclaimed_shares: int
+    unclaimed_eth: Decimal
+
+    # Total claimable
+    total_claimable_eth: Decimal
+
+    # Validator counts (from on-chain)
+    total_validators: int
+    active_validators: int
+    exited_validators: int
+
+    # Validator details (from beacon chain, optional)
+    validator_details: list[Any] = []  # list[ValidatorInfo]
+    validators_by_status: dict[str, int] | None = None
+    avg_effectiveness: float | None = None
+
+    # APY metrics (optional, requires detailed lookup)
+    apy: APYMetrics | None = None
+
+    # Operator activation date (from earliest validator activation)
+    active_since: datetime | None = None
+
+    # Health status (optional, requires detailed lookup)
+    health: HealthStatus | None = None

src/data/__init__.py

@@ -0,0 +1 @@
+"""Data layer - on-chain and off-chain data fetching."""

src/data/beacon.py

@@ -0,0 +1,370 @@
+"""Beacon chain data fetching via beaconcha.in API."""
+
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+from enum import Enum
+
+import httpx
+
+from ..core.config import get_settings
+from .cache import cached
+
+# Beacon Chain constants
+BEACON_GENESIS = datetime(2020, 12, 1, 12, 0, 23, tzinfo=timezone.utc)
+SECONDS_PER_EPOCH = 32 * 12  # 384 seconds (32 slots × 12 seconds per slot)
+
+
+def epoch_to_datetime(epoch: int) -> datetime:
+    """Convert beacon chain epoch to datetime."""
+    return BEACON_GENESIS + timedelta(seconds=epoch * SECONDS_PER_EPOCH)
+
+
+def get_earliest_activation(validators: list["ValidatorInfo"]) -> datetime | None:
+    """Get the earliest activation date from a list of validators."""
+    epochs = [v.activation_epoch for v in validators if v.activation_epoch is not None]
+    if not epochs:
+        return None
+    return epoch_to_datetime(min(epochs))
+
+
+class ValidatorStatus(str, Enum):
+    """Validator lifecycle status on the beacon chain."""
+
+    PENDING_INITIALIZED = "pending_initialized"
+    PENDING_QUEUED = "pending_queued"
+    ACTIVE_ONGOING = "active_ongoing"
+    ACTIVE_EXITING = "active_exiting"
+    ACTIVE_SLASHED = "active_slashed"
+    EXITED_UNSLASHED = "exited_unslashed"
+    EXITED_SLASHED = "exited_slashed"
+    WITHDRAWAL_POSSIBLE = "withdrawal_possible"
+    WITHDRAWAL_DONE = "withdrawal_done"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_beaconcha(cls, status: str) -> "ValidatorStatus":
+        """Convert beaconcha.in status string to enum."""
+        status_map = {
+            "pending": cls.PENDING_QUEUED,
+            "active_online": cls.ACTIVE_ONGOING,
+            "active_offline": cls.ACTIVE_ONGOING,
+            "active": cls.ACTIVE_ONGOING,
+            "exiting_online": cls.ACTIVE_EXITING,
+            "exiting_offline": cls.ACTIVE_EXITING,
+            "exiting": cls.ACTIVE_EXITING,
+            "slashing_online": cls.ACTIVE_SLASHED,
+            "slashing_offline": cls.ACTIVE_SLASHED,
+            "slashing": cls.ACTIVE_SLASHED,
+            "slashed": cls.EXITED_SLASHED,
+            "exited": cls.EXITED_UNSLASHED,
+            "withdrawable": cls.WITHDRAWAL_POSSIBLE,
+            "withdrawn": cls.WITHDRAWAL_DONE,
+        }
+        return status_map.get(status.lower(), cls.UNKNOWN)
+
+    @property
+    def display_name(self) -> str:
+        """Human-readable display name."""
+        names = {
+            self.PENDING_INITIALIZED: "Pending (Init)",
+            self.PENDING_QUEUED: "Pending",
+            self.ACTIVE_ONGOING: "Active",
+            self.ACTIVE_EXITING: "Exiting",
+            self.ACTIVE_SLASHED: "Slashed",
+            self.EXITED_UNSLASHED: "Exited",
+            self.EXITED_SLASHED: "Slashed & Exited",
+            self.WITHDRAWAL_POSSIBLE: "Withdrawable",
+            self.WITHDRAWAL_DONE: "Withdrawn",
+            self.UNKNOWN: "Unknown",
+        }
+        return names.get(self, "Unknown")
+
+    @property
+    def is_active(self) -> bool:
+        """Check if validator is currently active."""
+        return self in (self.ACTIVE_ONGOING, self.ACTIVE_EXITING, self.ACTIVE_SLASHED)
+
+    @property
+    def is_exited(self) -> bool:
+        """Check if validator has exited."""
+        return self in (
+            self.EXITED_UNSLASHED,
+            self.EXITED_SLASHED,
+            self.WITHDRAWAL_POSSIBLE,
+            self.WITHDRAWAL_DONE,
+        )
+
+
+class ValidatorInfo:
+    """Information about a single validator."""
+
+    def __init__(
+        self,
+        pubkey: str,
+        index: int | None = None,
+        status: ValidatorStatus = ValidatorStatus.UNKNOWN,
+        balance_gwei: int = 0,
+        effectiveness: float | None = None,
+        activation_epoch: int | None = None,
+        exit_epoch: int | None = None,
+    ):
+        self.pubkey = pubkey
+        self.index = index
+        self.status = status
+        self.balance_gwei = balance_gwei
+        self.effectiveness = effectiveness
+        self.activation_epoch = activation_epoch
+        self.exit_epoch = exit_epoch
+
+    @property
+    def balance_eth(self) -> Decimal:
+        """Balance in ETH."""
+        return Decimal(self.balance_gwei) / Decimal(10**9)
+
+    @property
+    def at_risk(self) -> bool:
+        """
+        Check if validator is at risk due to low balance.
+
+        A validator with effective balance < 32 ETH may face withdrawal penalties
+        when exiting, as the difference will be confiscated from the operator's bond.
+        """
+        # Only active validators can be "at risk" in this sense
+        if not self.status.is_active:
+            return False
+        # 32 ETH = 32_000_000_000 gwei
+        return self.balance_gwei < 32_000_000_000
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "pubkey": self.pubkey,
+            "index": self.index,
+            "status": self.status.value,
+            "status_display": self.status.display_name,
+            "balance_eth": float(self.balance_eth),
+            "effectiveness": self.effectiveness,
+            "activation_epoch": self.activation_epoch,
+            "exit_epoch": self.exit_epoch,
+            "at_risk": self.at_risk,
+        }
+
+
+class BeaconDataProvider:
+    """Fetches validator data from beaconcha.in API."""
+
+    def __init__(self):
+        self.settings = get_settings()
+        self.base_url = self.settings.beacon_api_url.rstrip("/")
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get headers for API requests, including API key if configured."""
+        headers = {"accept": "application/json"}
+        if self.settings.beacon_api_key:
+            headers["apikey"] = self.settings.beacon_api_key
+        return headers
+
+    @cached(ttl=300)  # Cache for 5 minutes
+    async def get_validators_by_pubkeys(
+        self, pubkeys: list[str]
+    ) -> list[ValidatorInfo]:
+        """
+        Fetch validator info for multiple pubkeys.
+
+        beaconcha.in supports comma-separated pubkeys (up to 100).
+        """
+        if not pubkeys:
+            return []
+
+        validators = []
+        batch_size = 100  # beaconcha.in limit
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            for i in range(0, len(pubkeys), batch_size):
+                batch = pubkeys[i : i + batch_size]
+                pubkeys_param = ",".join(batch)
+
+                try:
+                    response = await client.get(
+                        f"{self.base_url}/validator/{pubkeys_param}",
+                        headers=self._get_headers(),
+                    )
+
+                    if response.status_code == 200:
+                        data = response.json().get("data", [])
+                        # API returns single object if only one validator
+                        if isinstance(data, dict):
+                            data = [data]
+
+                        for v in data:
+                            validators.append(self._parse_validator(v))
+                    elif response.status_code == 404:
+                        # Validators not found - create placeholder entries
+                        for pubkey in batch:
+                            validators.append(
+                                ValidatorInfo(
+                                    pubkey=pubkey,
+                                    status=ValidatorStatus.PENDING_INITIALIZED,
+                                )
+                            )
+                except Exception:
+                    # On error, add unknown status for this batch
+                    for pubkey in batch:
+                        validators.append(
+                            ValidatorInfo(pubkey=pubkey, status=ValidatorStatus.UNKNOWN)
+                        )
+
+        return validators
+
+    def _parse_validator(self, data: dict) -> ValidatorInfo:
+        """Parse beaconcha.in validator response."""
+        return ValidatorInfo(
+            pubkey=data.get("pubkey", ""),
+            index=data.get("validatorindex"),
+            status=ValidatorStatus.from_beaconcha(data.get("status", "unknown")),
+            balance_gwei=data.get("balance", 0),
+            effectiveness=data.get("effectiveness"),
+            activation_epoch=data.get("activationepoch"),
+            exit_epoch=data.get("exitepoch") if data.get("exitepoch") is not None and data.get("exitepoch") >= 0 else None,
+        )
+
+    @cached(ttl=300)
+    async def get_validator_performance(
+        self, validator_index: int
+    ) -> dict | None:
+        """Get detailed performance metrics for a validator."""
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            try:
+                response = await client.get(
+                    f"{self.base_url}/validator/{validator_index}/performance",
+                    headers=self._get_headers(),
+                )
+
+                if response.status_code == 200:
+                    return response.json().get("data")
+            except Exception:
+                pass
+
+        return None
+
+    @cached(ttl=300)
+    async def get_validator_income(
+        self, validator_indices: list[int], days: int = 28
+    ) -> dict:
+        """
+        Fetch validator income for a period.
+
+        Uses the /validator/{indices}/incomedetailhistory endpoint.
+        Returns total consensus rewards in ETH for the period.
+
+        Args:
+            validator_indices: List of validator indices to query
+            days: Number of days of history to fetch (7 or 28)
+        """
+        if not validator_indices:
+            return {"total_income_eth": Decimal(0), "days": days}
+
+        total_income_gwei = 0
+        batch_size = 100  # beaconcha.in limit
+
+        # Calculate epoch limit (~225 epochs per day)
+        epoch_limit = days * 225
+
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            for i in range(0, len(validator_indices), batch_size):
+                batch = validator_indices[i : i + batch_size]
+                indices_param = ",".join(str(idx) for idx in batch)
+
+                try:
+                    response = await client.get(
+                        f"{self.base_url}/validator/{indices_param}/incomedetailhistory",
+                        params={"limit": epoch_limit},
+                        headers=self._get_headers(),
+                    )
+
+                    if response.status_code == 200:
+                        data = response.json().get("data", [])
+                        # Handle single validator response (dict instead of list)
+                        if isinstance(data, dict):
+                            data = [data]
+
+                        for entry in data:
+                            # Each entry has income breakdown by reward type
+                            # API returns: attestation_source_reward, attestation_target_reward,
+                            # attestation_head_reward (not a "total" field)
+                            income = entry.get("income", {})
+                            if isinstance(income, dict):
+                                # Sum all reward types (values are in gwei)
+                                total_income_gwei += sum(income.values())
+                            elif isinstance(income, int):
+                                total_income_gwei += income
+                except Exception:
+                    # On error, continue with partial data
+                    pass
+
+        return {
+            "total_income_eth": Decimal(total_income_gwei) / Decimal(10**9),
+            "days": days,
+        }
+
+
+def aggregate_validator_status(validators: list[ValidatorInfo]) -> dict[str, int]:
+    """
+    Aggregate validator statuses into counts.
+
+    Returns dict like: {"active": 198, "pending": 1, "exited": 1, "slashed": 0}
+    """
+    counts = {
+        "active": 0,
+        "pending": 0,
+        "exiting": 0,
+        "exited": 0,
+        "slashed": 0,
+        "unknown": 0,
+    }
+
+    for v in validators:
+        if v.status.is_active and v.status != ValidatorStatus.ACTIVE_SLASHED:
+            if v.status == ValidatorStatus.ACTIVE_EXITING:
+                counts["exiting"] += 1
+            else:
+                counts["active"] += 1
+        elif v.status in (ValidatorStatus.PENDING_INITIALIZED, ValidatorStatus.PENDING_QUEUED):
+            counts["pending"] += 1
+        elif v.status.is_exited:
+            if v.status == ValidatorStatus.EXITED_SLASHED:
+                counts["slashed"] += 1
+            else:
+                counts["exited"] += 1
+        elif v.status == ValidatorStatus.ACTIVE_SLASHED:
+            counts["slashed"] += 1
+        else:
+            counts["unknown"] += 1
+
+    return counts
+
+
+def calculate_avg_effectiveness(validators: list[ValidatorInfo]) -> float | None:
+    """Calculate average attestation effectiveness across validators."""
+    active_with_effectiveness = [
+        v for v in validators if v.status.is_active and v.effectiveness is not None
+    ]
+
+    if not active_with_effectiveness:
+        return None
+
+    total = sum(v.effectiveness for v in active_with_effectiveness)
+    return total / len(active_with_effectiveness)
+
+
+def count_at_risk_validators(validators: list[ValidatorInfo]) -> int:
+    """Count validators with balance < 32 ETH (at risk of withdrawal penalty)."""
+    return sum(1 for v in validators if v.at_risk)
+
+
+def count_slashed_validators(validators: list[ValidatorInfo]) -> int:
+    """Count slashed validators."""
+    return sum(
+        1 for v in validators
+        if v.status in (ValidatorStatus.ACTIVE_SLASHED, ValidatorStatus.EXITED_SLASHED)
+    )

src/data/cache.py

@@ -0,0 +1,67 @@
+"""Simple in-memory cache with TTL support."""
+
+import hashlib
+from datetime import datetime, timedelta
+from functools import wraps
+from typing import Any, Callable
+
+from ..core.config import get_settings
+
+
+class SimpleCache:
+    """Simple in-memory cache with TTL. Safe for single-threaded async but not thread-safe."""
+
+    def __init__(self, default_ttl: int | None = None):
+        self._cache: dict[str, tuple[Any, datetime]] = {}
+        self._default_ttl = default_ttl or get_settings().cache_ttl_seconds
+
+    def get(self, key: str) -> Any | None:
+        """Get value from cache if not expired."""
+        if key in self._cache:
+            value, expiry = self._cache[key]
+            if datetime.now() < expiry:
+                return value
+            del self._cache[key]
+        return None
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """Set value in cache with TTL."""
+        expiry = datetime.now() + timedelta(seconds=ttl or self._default_ttl)
+        self._cache[key] = (value, expiry)
+
+    def clear(self) -> None:
+        """Clear all cached values."""
+        self._cache.clear()
+
+
+# Global cache instance
+_cache = SimpleCache()
+
+
+def cached(ttl: int | None = None) -> Callable:
+    """Decorator for caching async function results."""
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Create cache key from function name and arguments
+            # Use repr() for proper tuple/list representation to avoid collisions
+            key_data = f"{func.__module__}.{func.__name__}:{repr(args)}:{repr(sorted(kwargs.items()))}"
+            cache_key = hashlib.md5(key_data.encode()).hexdigest()
+
+            cached_result = _cache.get(cache_key)
+            if cached_result is not None:
+                return cached_result
+
+            result = await func(*args, **kwargs)
+            _cache.set(cache_key, result, ttl)
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def get_cache() -> SimpleCache:
+    """Get the global cache instance."""
+    return _cache

src/data/etherscan.py

@@ -0,0 +1,78 @@
+"""Etherscan API client for event queries."""
+
+import httpx
+from web3 import Web3
+
+from ..core.config import get_settings
+
+
+class EtherscanProvider:
+    """Query contract events via Etherscan API."""
+
+    BASE_URL = "https://api.etherscan.io/v2/api"
+
+    def __init__(self):
+        self.settings = get_settings()
+        self.api_key = self.settings.etherscan_api_key
+
+    def is_available(self) -> bool:
+        """Check if Etherscan API key is configured."""
+        return bool(self.api_key)
+
+    async def get_distribution_log_events(
+        self,
+        contract_address: str,
+        from_block: int,
+        to_block: str | int = "latest",
+    ) -> list[dict]:
+        """Query DistributionLogUpdated events from Etherscan."""
+        if not self.api_key:
+            return []
+
+        # Event topic: keccak256("DistributionLogUpdated(string)")
+        topic0 = "0x" + Web3.keccak(text="DistributionLogUpdated(string)").hex()
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.get(
+                self.BASE_URL,
+                params={
+                    "chainid": 1,
+                    "module": "logs",
+                    "action": "getLogs",
+                    "address": contract_address,
+                    "topic0": topic0,
+                    "fromBlock": from_block,
+                    "toBlock": to_block,
+                    "apikey": self.api_key,
+                },
+            )
+
+            data = response.json()
+            if data.get("status") != "1":
+                return []
+
+            results = []
+            for log in data.get("result", []):
+                # Decode the logCid from the data field
+                # The data is ABI-encoded string: offset (32 bytes) + length (32 bytes) + data
+                raw_data = log["data"]
+                # Skip the offset (0x40 = 64 chars after 0x) and length prefix
+                # String data starts at byte 64 (128 hex chars after 0x)
+                if len(raw_data) > 130:  # 0x + 128 chars minimum
+                    # Extract length from bytes 32-64
+                    length_hex = raw_data[66:130]
+                    length = int(length_hex, 16)
+                    # Extract string data starting at byte 64
+                    string_data = raw_data[130 : 130 + length * 2]
+                    try:
+                        log_cid = bytes.fromhex(string_data).decode("utf-8")
+                        results.append(
+                            {
+                                "block": int(log["blockNumber"], 16),
+                                "logCid": log_cid,
+                            }
+                        )
+                    except (ValueError, UnicodeDecodeError):
+                        continue
+
+            return sorted(results, key=lambda x: x["block"])