csm-dashboard 0.3.2__tar.gz → 0.3.5__tar.gz

csm_dashboard-0.3.5/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.3.5] - 2026-01-05
+
+### Added
+- **Web:** Withdrawal History section with Load/Hide button toggle
+- **Web:** Distribution History section with Load/Hide button toggle
+- **Web:** Next Distribution info (estimated date and rewards)
+- **Web:** Favicon support
+
+### Fixed
+- **CLI/Web:** unstETH withdrawals now correctly show as "unstETH" type with ETH amounts
+- **CLI:** Added total row to Withdrawal History table
+
+### Changed
+- **Web:** History toggles changed from checkboxes to buttons for better UX
+
+## [0.3.4] - 2025-12
+
+### Added
+- unstETH (Lido Withdrawal NFT) tracking for `claimRewardsUnstETH` claims
+- Withdrawal status tracking (Pending/Ready/Claimed)
+
+## [0.3.3] and earlier
+- See git history for previous changes

{csm_dashboard-0.3.2 → csm_dashboard-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csm-dashboard
-Version: 0.3.2
+Version: 0.3.5
 Summary: Lido CSM Operator Dashboard for tracking validator earnings
 Requires-Python: >=3.11
 Requires-Dist: fastapi>=0.104

csm_dashboard-0.3.5/my-lido-csm-dashboard.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<Container version="2">
+  <Name>lido-csm-dashboard</Name>
+  <Repository>0xdespot/lido-csm-dashboard:latest</Repository>
+  <Registry>https://hub.docker.com/r/0xdespot/lido-csm-dashboard</Registry>
+  <Branch>
+    <Tag>latest</Tag>
+    <TagDescription>Latest stable release</TagDescription>
+  </Branch>
+  <Network>bridge</Network>
+  <Shell>sh</Shell>
+  <Privileged>false</Privileged>
+  <Support>https://github.com/0xdespot/lido-csm-dashboard/issues</Support>
+  <Project>https://github.com/0xdespot/lido-csm-dashboard</Project>
+  <Overview>Lido CSM Operator Dashboard - Track your Community Staking Module validator earnings, bond status, APY metrics, strikes, and health status. Features both a web UI and CLI interface.</Overview>
+  <Category>Crypto: Tools:</Category>
+  <WebUI>http://[IP]:[PORT:3000]/</WebUI>
+  <TemplateURL>https://raw.githubusercontent.com/0xdespot/lido-csm-dashboard/main/unraid-template.xml</TemplateURL>
+  <Icon>https://raw.githubusercontent.com/0xdespot/lido-csm-dashboard/main/img/logo.png</Icon>
+  <ExtraParams/>
+  <PostArgs/>
+  <DonateText/>
+  <DonateLink/>
+  <Requires/>
+  <Config Name="Web UI Port" Target="3000" Default="3000" Mode="tcp" Description="Web interface port" Type="Port" Display="always" Required="true" Mask="false">3000</Config>
+  <Config Name="App Data" Target="/app/data" Default="/mnt/user/appdata/lido-csm-dashboard" Mode="rw" Description="Application data and cache directory" Type="Path" Display="always" Required="false" Mask="false">/mnt/user/appdata/lido-csm-dashboard</Config>
+  <Config Name="ETH RPC URL" Target="ETH_RPC_URL" Default="https://eth.llamarpc.com" Mode="" Description="Ethereum RPC endpoint (default: llamarpc.com)" Type="Variable" Display="always" Required="false" Mask="false">https://eth.llamarpc.com</Config>
+  <Config Name="Beacon API URL" Target="BEACON_API_URL" Default="https://beaconcha.in/api/v1" Mode="" Description="Beacon chain API endpoint (default: beaconcha.in)" Type="Variable" Display="always" Required="false" Mask="false">https://beaconcha.in/api/v1</Config>
+  <Config Name="Beacon API Key" Target="BEACON_API_KEY" Default="" Mode="" Description="Optional - beaconcha.in API key for higher rate limits" Type="Variable" Display="always" Required="false" Mask="true"/>
+  <Config Name="Etherscan API Key" Target="ETHERSCAN_API_KEY" Default="" Mode="" Description="Optional - enables withdrawal history tracking" Type="Variable" Display="always" Required="false" Mask="true"/>
+  <Config Name="TheGraph API Key" Target="THEGRAPH_API_KEY" Default="" Mode="" Description="Optional - enables historical stETH APR data" Type="Variable" Display="always" Required="false" Mask="true"/>
+</Container>

{csm_dashboard-0.3.2 → csm_dashboard-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csm-dashboard"
-version = "0.3.2"
+version = "0.3.5"
 description = "Lido CSM Operator Dashboard for tracking validator earnings"
 readme = "README.md"
 requires-python = ">=3.11"

csm_dashboard-0.3.5/src/abis/WithdrawalQueueERC721.json

@@ -0,0 +1,47 @@
+[
+  {
+    "name": "WithdrawalRequested",
+    "type": "event",
+    "anonymous": false,
+    "inputs": [
+      {"indexed": true, "name": "requestId", "type": "uint256"},
+      {"indexed": true, "name": "requestor", "type": "address"},
+      {"indexed": true, "name": "owner", "type": "address"},
+      {"indexed": false, "name": "amountOfStETH", "type": "uint256"},
+      {"indexed": false, "name": "amountOfShares", "type": "uint256"}
+    ]
+  },
+  {
+    "name": "WithdrawalClaimed",
+    "type": "event",
+    "anonymous": false,
+    "inputs": [
+      {"indexed": true, "name": "requestId", "type": "uint256"},
+      {"indexed": true, "name": "owner", "type": "address"},
+      {"indexed": true, "name": "receiver", "type": "address"},
+      {"indexed": false, "name": "amountOfETH", "type": "uint256"}
+    ]
+  },
+  {
+    "name": "getWithdrawalStatus",
+    "type": "function",
+    "stateMutability": "view",
+    "inputs": [
+      {"name": "_requestIds", "type": "uint256[]"}
+    ],
+    "outputs": [
+      {
+        "name": "statuses",
+        "type": "tuple[]",
+        "components": [
+          {"name": "amountOfStETH", "type": "uint256"},
+          {"name": "amountOfShares", "type": "uint256"},
+          {"name": "owner", "type": "address"},
+          {"name": "timestamp", "type": "uint256"},
+          {"name": "isFinalized", "type": "bool"},
+          {"name": "isClaimed", "type": "bool"}
+        ]
+      }
+    ]
+  }
+]

{csm_dashboard-0.3.2 → csm_dashboard-0.3.5}/src/cli/commands.py

@@ -582,7 +582,9 @@ def rewards(
         withdrawal_table = Table(title="Withdrawal History")
         withdrawal_table.add_column("#", style="cyan", justify="right")
         withdrawal_table.add_column("Date", style="white")
-        withdrawal_table.add_column("Amount (stETH)", style="green", justify="right")
+        withdrawal_table.add_column("Type", style="magenta")
+        withdrawal_table.add_column("Amount", style="green", justify="right")
+        withdrawal_table.add_column("Status", style="yellow")
         withdrawal_table.add_column("Tx Hash", style="dim")
 
         for i, w in enumerate(rewards.withdrawals, 1):
@@ -592,16 +594,73 @@ def rewards(
             except (ValueError, TypeError):
                 w_date = w.timestamp[:10] if w.timestamp else "--"
 
+            # Determine display values based on type
+            withdrawal_type = w.withdrawal_type if w.withdrawal_type else "stETH"
+
+            # For unstETH, show claimed ETH if available, otherwise requested stETH
+            if withdrawal_type == "unstETH" and w.claimed_eth is not None:
+                amount_str = f"{w.claimed_eth:.4f} ETH"
+            else:
+                amount_str = f"{w.eth_value:.4f} stETH"
+
+            # Status column for unstETH
+            if withdrawal_type == "unstETH" and w.status:
+                status_colors = {
+                    "pending": "[yellow]Pending[/yellow]",
+                    "finalized": "[blue]Ready[/blue]",
+                    "claimed": "[green]Claimed[/green]",
+                    "unknown": "[dim]Unknown[/dim]",
+                }
+                status_str = status_colors.get(w.status, w.status)
+            elif withdrawal_type != "unstETH":
+                status_str = "[green]Claimed[/green]"
+            else:
+                status_str = "--"
+
             withdrawal_table.add_row(
                 str(i),
                 w_date,
-                f"{w.eth_value:.4f}",
+                withdrawal_type,
+                amount_str,
+                status_str,
                 f"{w.tx_hash[:10]}..." if w.tx_hash else "--",
             )
 
         console.print(withdrawal_table)
+
+        # Show totals
+        steth_total = sum(
+            w.eth_value for w in rewards.withdrawals
+            if w.withdrawal_type != "unstETH"
+        )
+        unsteth_claimed_total = sum(
+            w.claimed_eth for w in rewards.withdrawals
+            if w.withdrawal_type == "unstETH" and w.claimed_eth is not None
+        )
+        if steth_total > 0 or unsteth_claimed_total > 0:
+            total_parts = []
+            if steth_total > 0:
+                total_parts.append(f"{steth_total:.4f} stETH")
+            if unsteth_claimed_total > 0:
+                total_parts.append(f"{unsteth_claimed_total:.4f} ETH")
+            console.print(f"[bold]Total claimed:[/bold] {' + '.join(total_parts)}")
         console.print()
 
+        # Show pending unstETH summary if any
+        pending_unsteth = [
+            w for w in rewards.withdrawals
+            if w.withdrawal_type == "unstETH"
+            and w.status in ("pending", "finalized")
+        ]
+        if pending_unsteth:
+            pending_total = sum(w.eth_value for w in pending_unsteth)
+            ready_count = sum(1 for w in pending_unsteth if w.status == "finalized")
+            console.print(
+                f"[yellow]Note: {len(pending_unsteth)} unstETH request(s) "
+                f"({ready_count} ready to claim) totaling ~{pending_total:.4f} stETH[/yellow]"
+            )
+            console.print()
+
 
 @app.command()
 def health(

{csm_dashboard-0.3.2 → csm_dashboard-0.3.5}/src/core/config.py

@@ -37,6 +37,7 @@ class Settings(BaseSettings):
     csfeedistributor_address: str = "0xD99CC66fEC647E68294C6477B40fC7E0F6F618D0"
     csstrikes_address: str = "0xaa328816027F2D32B9F56d190BC9Fa4A5C07637f"
     steth_address: str = "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84"
+    withdrawal_queue_address: str = "0x889edC2eDab5f40e902b864aD4d7AdE8E412F9B1"
 
 
 @lru_cache

{csm_dashboard-0.3.2 → csm_dashboard-0.3.5}/src/core/contracts.py

@@ -16,3 +16,4 @@ CSMODULE_ABI = load_abi("CSModule")
 CSACCOUNTING_ABI = load_abi("CSAccounting")
 CSFEEDISTRIBUTOR_ABI = load_abi("CSFeeDistributor")
 STETH_ABI = load_abi("stETH")
+WITHDRAWAL_QUEUE_ABI = load_abi("WithdrawalQueueERC721")

{csm_dashboard-0.3.2 → csm_dashboard-0.3.5}/src/core/types.py

@@ -70,6 +70,16 @@ class WithdrawalEvent(BaseModel):
     eth_value: float
     tx_hash: str
 
+    # Withdrawal type: "stETH" (direct transfer) or "unstETH" (withdrawal NFT)
+    withdrawal_type: str = "stETH"
+
+    # unstETH-specific fields (only populated for unstETH type)
+    request_id: int | None = None
+    status: str | None = None  # "pending", "finalized", or "claimed"
+    claimed_eth: float | None = None  # Actual ETH received when claimed
+    claim_tx_hash: str | None = None  # Transaction where claim occurred
+    claim_timestamp: str | None = None  # When the claim happened
+
 
 class APYMetrics(BaseModel):
     """APY calculations for an operator.

csm_dashboard-0.3.5/src/data/etherscan.py

@@ -0,0 +1,297 @@
+"""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"])
+
+    async def get_transfer_events(
+        self,
+        token_address: str,
+        from_address: str,
+        to_address: str,
+        from_block: int,
+        to_block: str | int = "latest",
+    ) -> list[dict]:
+        """Query Transfer events from Etherscan for a specific from/to pair."""
+        if not self.api_key:
+            return []
+
+        # Event topic: keccak256("Transfer(address,address,uint256)")
+        topic0 = "0x" + Web3.keccak(text="Transfer(address,address,uint256)").hex()
+        # topic1 is indexed 'from' address (padded to 32 bytes)
+        topic1 = "0x" + from_address.lower().replace("0x", "").zfill(64)
+        # topic2 is indexed 'to' address (padded to 32 bytes)
+        topic2 = "0x" + to_address.lower().replace("0x", "").zfill(64)
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.get(
+                self.BASE_URL,
+                params={
+                    "chainid": 1,
+                    "module": "logs",
+                    "action": "getLogs",
+                    "address": token_address,
+                    "topic0": topic0,
+                    "topic1": topic1,
+                    "topic2": topic2,
+                    "topic0_1_opr": "and",
+                    "topic1_2_opr": "and",
+                    "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", []):
+                # The data field contains the non-indexed value (amount)
+                raw_data = log["data"]
+                try:
+                    value = int(raw_data, 16)
+                    results.append(
+                        {
+                            "block": int(log["blockNumber"], 16),
+                            "tx_hash": log["transactionHash"],
+                            "value": value,
+                        }
+                    )
+                except (ValueError, TypeError):
+                    continue
+
+            return sorted(results, key=lambda x: x["block"])
+
+    async def get_withdrawal_requested_events(
+        self,
+        contract_address: str,
+        requestor: str,
+        owner: str,
+        from_block: int,
+        to_block: str | int = "latest",
+    ) -> list[dict]:
+        """Query WithdrawalRequested events from Etherscan.
+
+        Args:
+            contract_address: WithdrawalQueue contract address
+            requestor: Address that requested the withdrawal (CSAccounting)
+            owner: Address that owns the unstETH NFT (reward_address)
+            from_block: Starting block
+            to_block: Ending block
+
+        Returns:
+            List of withdrawal request events
+        """
+        if not self.api_key:
+            return []
+
+        # Event: WithdrawalRequested(uint256 indexed requestId, address indexed requestor,
+        #                            address indexed owner, uint256 amountOfStETH, uint256 amountOfShares)
+        topic0 = (
+            "0x"
+            + Web3.keccak(
+                text="WithdrawalRequested(uint256,address,address,uint256,uint256)"
+            ).hex()
+        )
+        # topic1 is indexed requestId - not filtering on this
+        # topic2 is indexed 'requestor' address (padded to 32 bytes)
+        topic2 = "0x" + requestor.lower().replace("0x", "").zfill(64)
+        # topic3 is indexed 'owner' address (padded to 32 bytes)
+        topic3 = "0x" + owner.lower().replace("0x", "").zfill(64)
+
+        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,
+                    "topic2": topic2,
+                    "topic3": topic3,
+                    "topic0_2_opr": "and",
+                    "topic2_3_opr": "and",
+                    "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", []):
+                try:
+                    # requestId is topic1 (indexed)
+                    request_id = int(log["topics"][1], 16)
+                    # amountOfStETH and amountOfShares are in data field
+                    raw_data = log["data"]
+                    # Each uint256 is 64 hex chars (32 bytes)
+                    amount_steth = int(raw_data[2:66], 16)
+                    amount_shares = int(raw_data[66:130], 16)
+
+                    results.append(
+                        {
+                            "request_id": request_id,
+                            "block": int(log["blockNumber"], 16),
+                            "tx_hash": log["transactionHash"],
+                            "amount_steth": amount_steth,
+                            "amount_shares": amount_shares,
+                        }
+                    )
+                except (ValueError, TypeError, IndexError):
+                    continue
+
+            return sorted(results, key=lambda x: x["block"])
+
+    async def get_withdrawal_claimed_events(
+        self,
+        contract_address: str,
+        receiver: str,
+        from_block: int,
+        to_block: str | int = "latest",
+    ) -> list[dict]:
+        """Query WithdrawalClaimed events from Etherscan.
+
+        Args:
+            contract_address: WithdrawalQueue contract address
+            receiver: Address that received the ETH (reward_address)
+            from_block: Starting block
+            to_block: Ending block
+
+        Returns:
+            List of withdrawal claim events
+        """
+        if not self.api_key:
+            return []
+
+        # Event: WithdrawalClaimed(uint256 indexed requestId, address indexed owner,
+        #                          address indexed receiver, uint256 amountOfETH)
+        topic0 = (
+            "0x"
+            + Web3.keccak(
+                text="WithdrawalClaimed(uint256,address,address,uint256)"
+            ).hex()
+        )
+        # topic3 is indexed 'receiver' address (padded to 32 bytes)
+        topic3 = "0x" + receiver.lower().replace("0x", "").zfill(64)
+
+        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,
+                    "topic3": topic3,
+                    "topic0_3_opr": "and",
+                    "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", []):
+                try:
+                    # requestId is topic1 (indexed)
+                    request_id = int(log["topics"][1], 16)
+                    # amountOfETH is in data field
+                    amount_eth = int(log["data"], 16) / 10**18
+
+                    results.append(
+                        {
+                            "request_id": request_id,
+                            "tx_hash": log["transactionHash"],
+                            "amount_eth": amount_eth,
+                            "block": int(log["blockNumber"], 16),
+                        }
+                    )
+                except (ValueError, TypeError, IndexError):
+                    continue
+
+            return sorted(results, key=lambda x: x["block"])