csm-dashboard 0.2.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

src/data/ipfs_logs.py

@@ -3,6 +3,7 @@
 import json
 import time
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from decimal import Decimal
 from pathlib import Path
 
@@ -11,6 +12,19 @@ import httpx
 from ..core.config import get_settings
 
 
+# Ethereum Beacon Chain genesis timestamp (Dec 1, 2020 12:00:23 UTC)
+BEACON_GENESIS = 1606824023
+
+
+def epoch_to_datetime(epoch: int) -> datetime:
+    """Convert beacon chain epoch to datetime.
+
+    Each epoch is 32 slots * 12 seconds = 384 seconds.
+    """
+    timestamp = BEACON_GENESIS + (epoch * 384)
+    return datetime.fromtimestamp(timestamp, tz=timezone.utc)
+
+
 @dataclass
 class FrameData:
     """Data from a single distribution frame."""
@@ -20,6 +34,7 @@ class FrameData:
     log_cid: str
     block_number: int
     distributed_rewards: int  # For specific operator, in wei
+    validator_count: int  # Number of validators for operator in this frame
 
 
 class IPFSLogProvider:
@@ -27,7 +42,6 @@ class IPFSLogProvider:
 
     # IPFS gateways to try in order
     GATEWAYS = [
-        "https://dweb.link/ipfs/",
         "https://ipfs.io/ipfs/",
         "https://cloudflare-ipfs.com/ipfs/",
     ]
@@ -113,6 +127,9 @@ class IPFSLogProvider:
         Extract operator's distributed_rewards for a frame.
 
         Returns rewards in wei (shares), or None if operator not in frame.
+
+        Note: The IPFS log field name changed from "distributed" to "distributed_rewards"
+        around Dec 2025. We check both for backwards compatibility.
         """
         operators = log_data.get("operators", {})
         op_key = str(operator_id)
@@ -120,7 +137,12 @@ class IPFSLogProvider:
         if op_key not in operators:
             return None
 
-        return operators[op_key].get("distributed_rewards", 0)
+        op_data = operators[op_key]
+        # Handle both new and old field names for backwards compatibility
+        rewards = op_data.get("distributed_rewards")
+        if rewards is None:
+            rewards = op_data.get("distributed")  # Fallback to old field name
+        return rewards if rewards is not None else 0
 
     def get_frame_info(self, log_data: dict) -> tuple[int, int]:
         """
@@ -133,6 +155,22 @@ class IPFSLogProvider:
             return (0, 0)
         return (frame[0], frame[1])
 
+    def get_operator_validator_count(self, log_data: dict, operator_id: int) -> int:
+        """
+        Get the number of validators for an operator in a frame.
+
+        Returns the count of validators, or 0 if operator not in frame.
+        """
+        operators = log_data.get("operators", {})
+        op_key = str(operator_id)
+
+        if op_key not in operators:
+            return 0
+
+        op_data = operators[op_key]
+        validators = op_data.get("validators", {})
+        return len(validators)
+
     async def get_operator_history(
         self,
         operator_id: int,
@@ -164,6 +202,7 @@ class IPFSLogProvider:
                 continue
 
             start_epoch, end_epoch = self.get_frame_info(log_data)
+            validator_count = self.get_operator_validator_count(log_data, operator_id)
 
             frames.append(
                 FrameData(
@@ -172,6 +211,7 @@ class IPFSLogProvider:
                     log_cid=cid,
                     block_number=block,
                     distributed_rewards=rewards,
+                    validator_count=validator_count,
                 )
             )
 

src/data/lido_api.py

@@ -2,9 +2,11 @@
 
 import httpx
 
+from ..core.config import get_settings
 from .cache import cached
 
 LIDO_API_BASE = "https://eth-api.lido.fi/v1"
+LIDO_SUBGRAPH_ID = "Sxx812XgeKyzQPaBpR5YZWmGV5fZuBaPdh7DFhzSwiQ"
 
 
 class LidoAPIProvider:
@@ -33,3 +35,106 @@ class LidoAPIProvider:
                 pass
 
         return {"apr": None, "timestamp": None}
+
+    @cached(ttl=3600)  # Cache for 1 hour
+    async def get_historical_apr_data(self) -> list[dict]:
+        """Fetch historical APR data from Lido subgraph.
+
+        Returns list of {block, apr, blockTime} sorted by block ascending.
+        Returns empty list if API key not configured or query fails.
+        """
+        settings = get_settings()
+        if not settings.thegraph_api_key:
+            return []
+
+        # Query in descending order to get most recent 1000 entries
+        # (CSM frames are at blocks 21M+, we need recent data)
+        query = """
+        {
+          totalRewards(first: 1000, orderBy: block, orderDirection: desc) {
+            apr
+            block
+            blockTime
+          }
+        }
+        """
+
+        endpoint = f"https://gateway-arbitrum.network.thegraph.com/api/{settings.thegraph_api_key}/subgraphs/id/{LIDO_SUBGRAPH_ID}"
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            try:
+                response = await client.post(
+                    endpoint,
+                    json={"query": query},
+                    headers={"Content-Type": "application/json"},
+                )
+                if response.status_code == 200:
+                    data = response.json()
+                    results = data.get("data", {}).get("totalRewards", [])
+                    # Reverse to get ascending order (oldest to newest) for binary search
+                    return list(reversed(results))
+            except Exception:
+                pass
+
+        return []
+
+    def get_apr_for_block(self, apr_data: list[dict], target_block: int) -> float | None:
+        """Find the APR for a specific block number.
+
+        Returns the APR from the oracle report closest to (but not after) target_block.
+        """
+        if not apr_data:
+            return None
+
+        # Find the closest report at or before target_block
+        closest = None
+        for entry in apr_data:
+            block = int(entry["block"])
+            if block <= target_block:
+                closest = entry
+            else:
+                break  # apr_data is sorted ascending
+
+        return float(closest["apr"]) if closest else None
+
+    def get_average_apr_for_range(
+        self, apr_data: list[dict], start_timestamp: int, end_timestamp: int
+    ) -> float | None:
+        """Calculate average APR for a time range.
+
+        Averages all APR values from oracle reports within the given timestamp range.
+        Falls back to the closest APR before the range if no reports fall within.
+
+        Args:
+            apr_data: List of {block, apr, blockTime} sorted by block ascending
+            start_timestamp: Unix timestamp for range start
+            end_timestamp: Unix timestamp for range end
+
+        Returns:
+            Average APR as a percentage, or None if no data available
+        """
+        if not apr_data:
+            return None
+
+        # Find all APR reports within the time range
+        reports_in_range = []
+        closest_before = None
+
+        for entry in apr_data:
+            block_time = int(entry["blockTime"])
+            if block_time < start_timestamp:
+                closest_before = entry  # Keep track of most recent before range
+            elif block_time <= end_timestamp:
+                reports_in_range.append(entry)
+            else:
+                break  # Past the range, stop searching
+
+        if reports_in_range:
+            # Average all reports within the range
+            total_apr = sum(float(r["apr"]) for r in reports_in_range)
+            return total_apr / len(reports_in_range)
+        elif closest_before:
+            # No reports in range, use the closest one before
+            return float(closest_before["apr"])
+
+        return None

src/data/onchain.py

@@ -122,6 +122,81 @@ class OnChainDataProvider:
 
         return None
 
+    @cached(ttl=300)
+    async def get_bond_curve_id(self, operator_id: int) -> int:
+        """Get the bond curve ID for an operator.
+
+        Returns:
+            0 = Permissionless (2.4 ETH first validator, 1.3 ETH subsequent)
+            1 = ICS/Legacy EA (1.5 ETH first validator, 1.3 ETH subsequent)
+        """
+        try:
+            return self.csaccounting.functions.getBondCurveId(operator_id).call()
+        except Exception:
+            # Fall back to 0 (Permissionless) if call fails
+            return 0
+
+    @staticmethod
+    def calculate_required_bond(validator_count: int, curve_id: int = 0) -> Decimal:
+        """Calculate required bond for a given validator count and curve type.
+
+        Args:
+            validator_count: Number of validators
+            curve_id: Bond curve ID from CSAccounting contract
+
+        Returns:
+            Required bond in ETH
+
+        Note:
+            Curve IDs on mainnet CSM:
+            - Curve 0: Original permissionless (2 ETH first, 1.3 ETH subsequent) - deprecated
+            - Curve 1: Original ICS/EA (1.5 ETH first, 1.3 ETH subsequent) - deprecated
+            - Curve 2: Current permissionless default (1.5 ETH first, 1.3 ETH subsequent)
+            The contract returns curve points directly, but for estimation we use
+            standard formulas.
+        """
+        if validator_count <= 0:
+            return Decimal(0)
+
+        # Curve 2 is the current mainnet default (1.5 ETH first, 1.3 ETH subsequent)
+        # Curve 0/1 were the original curves, now deprecated
+        if curve_id == 0:  # Original Permissionless (deprecated)
+            first_bond = Decimal("2.0")
+        else:  # Curve 1, 2, etc - current default curves
+            first_bond = Decimal("1.5")
+
+        subsequent_bond = Decimal("1.3")
+
+        if validator_count == 1:
+            return first_bond
+        else:
+            return first_bond + (subsequent_bond * (validator_count - 1))
+
+    @staticmethod
+    def get_operator_type_name(curve_id: int) -> str:
+        """Get human-readable operator type from curve ID.
+
+        Args:
+            curve_id: Bond curve ID from CSAccounting contract
+
+        Returns:
+            Operator type name
+
+        Note:
+            Curve IDs on mainnet CSM:
+            - Curve 0: Original permissionless (deprecated)
+            - Curve 1: Original ICS/EA (deprecated)
+            - Curve 2: Current permissionless default
+        """
+        if curve_id == 0:
+            return "Permissionless (Legacy)"
+        elif curve_id == 1:
+            return "ICS/Legacy EA"
+        elif curve_id == 2:
+            return "Permissionless"
+        else:
+            return f"Custom (Curve {curve_id})"
+
     @cached(ttl=60)
     async def get_bond_summary(self, operator_id: int) -> BondSummary:
         """Get bond summary for an operator."""
@@ -256,3 +331,119 @@ class OnChainDataProvider:
                 return []
 
         return sorted(all_events, key=lambda x: x["block"])
+
+    @cached(ttl=3600)  # Cache for 1 hour
+    async def get_withdrawal_history(
+        self, reward_address: str, start_block: int | None = None
+    ) -> list[dict]:
+        """
+        Get withdrawal history for an operator's reward address.
+
+        Queries stETH Transfer events from CSAccounting to the reward address.
+        These represent when the operator claimed their rewards.
+        (Note: Claims flow CSFeeDistributor -> CSAccounting -> reward_address)
+
+        Args:
+            reward_address: The operator's reward address
+            start_block: Starting block number (default: CSM deployment ~20873000)
+
+        Returns:
+            List of withdrawal events with block, tx_hash, shares, and timestamp
+        """
+        if start_block is None:
+            start_block = 20873000  # CSM deployment block
+
+        reward_address = Web3.to_checksum_address(reward_address)
+        csaccounting_address = self.settings.csaccounting_address
+
+        # 1. Try Etherscan API first (most reliable)
+        etherscan = EtherscanProvider()
+        if etherscan.is_available():
+            events = await etherscan.get_transfer_events(
+                token_address=self.settings.steth_address,
+                from_address=csaccounting_address,
+                to_address=reward_address,
+                from_block=start_block,
+            )
+            if events:
+                # Enrich with block timestamps
+                return await self._enrich_withdrawal_events(events)
+
+        # 2. Try chunked RPC queries
+        events = await self._query_transfer_events_chunked(
+            csaccounting_address, reward_address, start_block
+        )
+        if events:
+            return await self._enrich_withdrawal_events(events)
+
+        return []
+
+    async def _query_transfer_events_chunked(
+        self,
+        from_address: str,
+        to_address: str,
+        start_block: int,
+        chunk_size: int = 10000,
+    ) -> list[dict]:
+        """Query Transfer events in smaller chunks."""
+        current_block = self.w3.eth.block_number
+        all_events = []
+
+        from_address = Web3.to_checksum_address(from_address)
+        to_address = Web3.to_checksum_address(to_address)
+
+        for from_blk in range(start_block, current_block, chunk_size):
+            to_blk = min(from_blk + chunk_size - 1, current_block)
+            try:
+                events = self.steth.events.Transfer.get_logs(
+                    from_block=from_blk,
+                    to_block=to_blk,
+                    argument_filters={
+                        "from": from_address,
+                        "to": to_address,
+                    },
+                )
+                for e in events:
+                    all_events.append(
+                        {
+                            "block": e["blockNumber"],
+                            "tx_hash": e["transactionHash"].hex(),
+                            "value": e["args"]["value"],
+                        }
+                    )
+            except Exception:
+                # If chunked queries fail, give up on this method
+                return []
+
+        return sorted(all_events, key=lambda x: x["block"])
+
+    async def _enrich_withdrawal_events(self, events: list[dict]) -> list[dict]:
+        """Add timestamps and ETH values to withdrawal events."""
+        from datetime import datetime, timezone
+
+        enriched = []
+        for event in events:
+            try:
+                # Get block timestamp
+                block = self.w3.eth.get_block(event["block"])
+                timestamp = datetime.fromtimestamp(
+                    block["timestamp"], tz=timezone.utc
+                ).isoformat()
+
+                # Convert shares to ETH (using current rate as approximation)
+                eth_value = await self.shares_to_eth(event["value"])
+
+                enriched.append(
+                    {
+                        "block_number": event["block"],
+                        "timestamp": timestamp,
+                        "shares": event["value"],
+                        "eth_value": float(eth_value),
+                        "tx_hash": event["tx_hash"],
+                    }
+                )
+            except Exception:
+                # Skip events we can't enrich
+                continue
+
+        return enriched

src/data/strikes.py

@@ -13,6 +13,22 @@ from ..core.config import get_settings
 from .cache import cached
 
 
+# Strike thresholds by operator type (curve_id)
+# Default (Permissionless): 3 strikes till key exit
+# ICS (Identified Community Staker): 4 strikes till key exit
+STRIKE_THRESHOLDS = {
+    0: 3,  # Permissionless (Legacy)
+    1: 4,  # ICS/Legacy EA
+    2: 3,  # Permissionless (current)
+}
+DEFAULT_STRIKE_THRESHOLD = 3
+
+
+def get_strike_threshold(curve_id: int) -> int:
+    """Get the strike threshold for ejection based on operator curve_id."""
+    return STRIKE_THRESHOLDS.get(curve_id, DEFAULT_STRIKE_THRESHOLD)
+
+
 @dataclass
 class ValidatorStrikes:
     """Strike information for a single validator."""
@@ -20,7 +36,8 @@ class ValidatorStrikes:
     pubkey: str
     strikes: list[int]  # Array of 6 values (0 or 1) representing strikes per frame
     strike_count: int  # Total strikes in the 6-frame window
-    at_ejection_risk: bool  # True if 3+ strikes (eligible for ejection)
+    strike_threshold: int  # Number of strikes required for ejection (3 or 4)
+    at_ejection_risk: bool  # True if strike_count >= strike_threshold
 
 
 class StrikesProvider:
@@ -141,12 +158,16 @@ class StrikesProvider:
             return None
         return await self._fetch_tree_from_ipfs(cid)
 
-    async def get_operator_strikes(self, operator_id: int) -> list[ValidatorStrikes]:
+    async def get_operator_strikes(
+        self, operator_id: int, curve_id: int | None = None
+    ) -> list[ValidatorStrikes]:
         """
         Get strikes for all validators belonging to an operator.
 
         Args:
             operator_id: The CSM operator ID
+            curve_id: The operator's bond curve ID (determines strike threshold)
+                     If None, defaults to 3 strikes (permissionless threshold)
 
         Returns:
             List of ValidatorStrikes for validators with any strikes.
@@ -159,6 +180,9 @@ class StrikesProvider:
         values = tree_data.get("values", [])
         operator_strikes = []
 
+        # Determine strike threshold based on operator type
+        strike_threshold = get_strike_threshold(curve_id) if curve_id is not None else DEFAULT_STRIKE_THRESHOLD
+
         for entry in values:
             value = entry.get("value", [])
             if len(value) < 3:
@@ -179,33 +203,42 @@ class StrikesProvider:
                     pubkey=pubkey,
                     strikes=strikes_array if isinstance(strikes_array, list) else [],
                     strike_count=strike_count,
-                    at_ejection_risk=strike_count >= 3,
+                    strike_threshold=strike_threshold,
+                    at_ejection_risk=strike_count >= strike_threshold,
                 )
             )
 
         return operator_strikes
 
     async def get_operator_strike_summary(
-        self, operator_id: int
+        self, operator_id: int, curve_id: int | None = None
     ) -> dict[str, int]:
         """
         Get a summary of strikes for an operator.
 
+        Args:
+            operator_id: The CSM operator ID
+            curve_id: The operator's bond curve ID (determines strike threshold)
+
         Returns:
             Dict with:
             - total_validators_with_strikes: Count of validators with any strikes
-            - validators_at_risk: Count of validators with 3+ strikes
+            - validators_at_risk: Count of validators at ejection risk (>= threshold)
+            - validators_near_ejection: Count one strike away from ejection
             - total_strikes: Sum of all strikes across all validators
             - max_strikes: Highest strike count on any single validator
+            - strike_threshold: The ejection threshold for this operator type
         """
-        strikes = await self.get_operator_strikes(operator_id)
+        strikes = await self.get_operator_strikes(operator_id, curve_id)
+        strike_threshold = get_strike_threshold(curve_id) if curve_id is not None else DEFAULT_STRIKE_THRESHOLD
 
         return {
             "total_validators_with_strikes": len(strikes),
             "validators_at_risk": sum(1 for s in strikes if s.at_ejection_risk),
-            "validators_near_ejection": sum(1 for s in strikes if s.strike_count == 2),
+            "validators_near_ejection": sum(1 for s in strikes if s.strike_count == strike_threshold - 1),
             "total_strikes": sum(s.strike_count for s in strikes),
             "max_strikes": max((s.strike_count for s in strikes), default=0),
+            "strike_threshold": strike_threshold,
         }
 
     def clear_cache(self) -> None: