csm-dashboard 0.2.1__tar.gz → 0.3.0__tar.gz

{csm_dashboard-0.2.1 → csm_dashboard-0.3.0}/Dockerfile

@@ -17,6 +17,11 @@ ENV PATH="/opt/venv/bin:$PATH"
 RUN pip install --upgrade pip && \
     pip install --no-cache-dir -r requirements.txt
 
+# Copy package files and install
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+
 # Final stage
 FROM python:3.11-slim
 
@@ -27,21 +32,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy virtual environment from builder
+# Copy virtual environment from builder (includes installed package)
 COPY --from=builder /opt/venv /opt/venv
 
-# Copy application code (includes abis inside src/)
-COPY src ./src
-
-# Create csm alias script
-RUN echo '#!/bin/sh\npython -m src.main "$@"' > /usr/local/bin/csm && \
-    chmod +x /usr/local/bin/csm
-
 # Set environment variables
 ENV PATH="/opt/venv/bin:$PATH" \
     PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONPATH=/app
+    PYTHONDONTWRITEBYTECODE=1
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
@@ -50,5 +47,5 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
 # Expose port for web dashboard
 EXPOSE 3000
 
-# Default command - run the web dashboard using csm alias
+# Default command - csm is now an entry point from pip install
 CMD ["csm", "serve", "--host", "0.0.0.0", "--port", "3000"]

{csm_dashboard-0.2.1 → csm_dashboard-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csm-dashboard
-Version: 0.2.1
+Version: 0.3.0
 Summary: Lido CSM Operator Dashboard for tracking validator earnings
 Requires-Python: >=3.11
 Requires-Dist: fastapi>=0.104
@@ -31,8 +31,11 @@ Track your Lido Community Staking Module (CSM) validator earnings, excess bond,
 - Look up operator by Ethereum address (manager or rewards address) or operator ID
 - View current bond vs required bond (excess is claimable)
 - Track cumulative rewards and unclaimed amounts
+- Operator type detection (Permissionless, ICS/Legacy EA, etc.)
 - Detailed validator status from beacon chain (with `--detailed` flag)
 - APY metrics: reward APY, bond APY (stETH rebase), and net APY
+- Full distribution history with per-frame breakdown (with `--history` flag)
+- Withdrawal/claim history tracking (with `--withdrawals` flag)
 - JSON output for scripting and automation
 - CLI for quick terminal lookups
 - Web interface for browser-based monitoring
@@ -85,6 +88,7 @@ Available settings:
 - `BEACON_API_URL`: Beacon chain API (default: https://beaconcha.in/api/v1)
 - `BEACON_API_KEY`: Optional API key for beaconcha.in (higher rate limits)
 - `ETHERSCAN_API_KEY`: Optional API key for Etherscan (recommended for accurate historical data)
+- `THEGRAPH_API_KEY`: Optional API key for The Graph (enables historical Bond APY per distribution frame)
 - `CACHE_TTL_SECONDS`: Cache duration in seconds (default: 300)
 
 ## Usage
@@ -128,6 +132,8 @@ csm rewards [ADDRESS] [OPTIONS]
 | `ADDRESS` | | Ethereum address (required unless `--id` is provided) |
 | `--id` | `-i` | Operator ID (skips address lookup, faster) |
 | `--detailed` | `-d` | Include validator status from beacon chain and APY metrics |
+| `--history` | `-H` | Show all historical distribution frames with per-frame APY |
+| `--withdrawals` | `-w` | Include withdrawal/claim history |
 | `--json` | `-j` | Output as JSON (same format as API) |
 | `--rpc` | `-r` | Custom RPC URL |
 
@@ -143,6 +149,12 @@ csm rewards --id 42
 # Get detailed validator info and APY
 csm rewards --id 42 --detailed
 
+# Show full distribution history with Previous/Current/Lifetime columns
+csm rewards --id 42 --history
+
+# Include withdrawal history
+csm rewards --id 42 --withdrawals
+
 # JSON output for scripting
 csm rewards --id 42 --json
 
@@ -226,17 +238,16 @@ csm rewards --id 333 --json
   "operator_id": 333,
   "manager_address": "0x6ac683C503CF210CCF88193ec7ebDe2c993f63a4",
   "reward_address": "0x55915Cf2115c4D6e9085e94c8dAD710cabefef31",
+  "curve_id": 2,
+  "operator_type": "Permissionless",
   "rewards": {
-    "current_bond_eth": 651.5523536856277,
+    "current_bond_eth": 651.55,
     "required_bond_eth": 650.2,
-    "excess_bond_eth": 1.3523536856277778,
-    "cumulative_rewards_shares": 8973877501313655495,
-    "cumulative_rewards_eth": 10.9642938931415,
-    "distributed_shares": 7867435720490255061,
-    "distributed_eth": 9.61244204773546,
-    "unclaimed_shares": 1106441780823400434,
-    "unclaimed_eth": 1.3518518454060409,
-    "total_claimable_eth": 2.7042055310338187
+    "excess_bond_eth": 1.35,
+    "cumulative_rewards_eth": 10.96,
+    "distributed_eth": 9.61,
+    "unclaimed_eth": 1.35,
+    "total_claimable_eth": 2.70
   },
   "validators": {
     "total": 500,
@@ -251,44 +262,68 @@ With `--detailed`, additional fields are included:
 ```json
 {
   "operator_id": 333,
-  "...": "...",
+  "curve_id": 2,
+  "operator_type": "Permissionless",
   "validators": {
     "total": 500,
     "active": 500,
     "exited": 0,
     "by_status": {
-      "active": 100,
+      "active": 500,
       "pending": 0,
       "exiting": 0,
       "exited": 0,
-      "slashed": 0,
-      "unknown": 0
+      "slashed": 0
     }
   },
   "performance": {
     "avg_effectiveness": 98.5
   },
   "apy": {
-    "historical_reward_apy_28d": 2.21,
-    "historical_reward_apy_ltd": 2.03,
-    "bond_apy": 2.54,
-    "net_apy_28d": 4.75,
-    "net_apy_ltd": 4.57
+    "current_distribution_apy": 2.77,
+    "current_bond_apr": 2.56,
+    "net_apy_28d": 5.33,
+    "lifetime_reward_apy": 2.80,
+    "lifetime_bond_apy": 2.60,
+    "lifetime_net_apy": 5.40
   },
   "active_since": "2025-02-16T12:00:00"
 }
 ```
 
+With `--history`, you also get the full distribution frame history:
+
+```json
+{
+  "apy": {
+    "frames": [
+      {
+        "frame_number": 1,
+        "start_date": "2025-03-14T00:00:00",
+        "end_date": "2025-04-11T00:00:00",
+        "rewards_eth": 1.2345,
+        "validator_count": 500,
+        "duration_days": 28.0,
+        "apy": 2.85
+      }
+    ]
+  }
+}
+```
+
 ## API Endpoints
 
 - `GET /api/operator/{address_or_id}` - Get operator rewards data
   - Query param: `?detailed=true` for validator status and APY
+  - Query param: `?history=true` for all historical distribution frames
+  - Query param: `?withdrawals=true` for withdrawal/claim history
+- `GET /api/operator/{address_or_id}/strikes` - Get detailed validator strikes
 - `GET /api/operators` - List all operators with rewards
 - `GET /api/health` - Health check
 
 ## Understanding APY Metrics
 
-The dashboard shows three APY metrics when using the `--detailed` flag:
+The dashboard shows three APY metrics when using the `--detailed` or `--history` flags:
 
 | Metric | What It Means |
 |--------|---------------|
@@ -296,16 +331,34 @@ The dashboard shows three APY metrics when using the `--detailed` flag:
 | **Bond APY** | Automatic growth of your stETH bond from protocol rebasing (same for all operators) |
 | **NET APY** | Total return = Reward APY + Bond APY |
 
+### Display Modes
+
+- **`--detailed`**: Shows only the Current frame column (simpler view)
+- **`--history`**: Shows Previous, Current, and Lifetime columns with full distribution history
+
 ### How APY is Calculated
 
-**Reward APY** is calculated from actual reward distribution data published by Lido. Every ~28 days, Lido calculates how much each operator earned and publishes a "distribution frame" to IPFS (a decentralized file storage network). The dashboard fetches all these historical frames to calculate both 28-day and lifetime APY.
+**Reward APY** is calculated from actual reward distribution data published by Lido. Every ~28 days, Lido calculates how much each operator earned and publishes a "distribution frame" to IPFS (a decentralized file storage network). The dashboard fetches all these historical frames to calculate APY.
+
+- **Current APY**: Based on the most recent distribution frame (~28 days)
+- **Previous APY**: Based on the second-to-last distribution frame
+- **Lifetime APY**: Duration-weighted average of all frames, using **per-frame bond requirements** for accuracy
+
+The **Lifetime APY** calculation is particularly sophisticated: it uses each frame's actual validator count to determine the bond requirement for that period, then calculates a duration-weighted average. This produces accurate lifetime APY even for operators who have grown significantly over time.
+
+**Bond APY** represents the stETH rebase rate—the automatic growth of your bond due to Ethereum staking rewards. This rate is set by the Lido protocol and applies equally to all operators.
+
+> **Note**: With a Graph API key configured (`THEGRAPH_API_KEY`), Bond APY shows the actual historical stETH rate for each distribution frame. Without the API key, it falls back to the current rate (marked with an asterisk).
 
-- **28-Day APY**: Based on the most recent ~28 days of reward distributions
-- **Lifetime APY**: Based on all periods where you earned rewards (excludes ramp-up periods with no rewards to avoid misleadingly low numbers)
+### Operator Types
 
-**Bond APY** represents the stETH rebase rate—the automatic growth of your bond due to Ethereum staking rewards. This rate is set by the Lido protocol and applies equally to all operators. The dashboard shows the current 7-day average rate from Lido's API.
+The dashboard detects your operator type from the CSAccounting bond curve:
 
-> **Note**: Bond APY shows the current stETH rate for both 28-Day and Lifetime columns, as historical rates aren't readily available.
+| Type | Description |
+|------|-------------|
+| **Permissionless** | Standard operators (Curve 2, current default) |
+| **Permissionless (Legacy)** | Early permissionless operators (Curve 0, deprecated) |
+| **ICS/Legacy EA** | Incentivized Community Stakers / Early Adopters (Curve 1) |
 
 ### Why You Might Want an Etherscan API Key
 
@@ -324,6 +377,18 @@ The actual reward data lives on IPFS and is always accessible. However, to *disc
 
 The free tier allows 5 calls/second, which is plenty for this dashboard.
 
+### Why You Might Want a Graph API Key
+
+The Graph provides historical stETH APR data from the Lido subgraph. Without this API key, Bond APY calculations use the current rate for all periods, which is less accurate.
+
+**How to get one (free):**
+1. Go to [thegraph.com/studio](https://thegraph.com/studio/)
+2. Connect your wallet and create an account
+3. Go to "API Keys" and create a new key
+4. Add to your `.env` file: `THEGRAPH_API_KEY=your_key_here`
+
+The free tier includes 100,000 queries/month, which is plenty for this dashboard.
+
 ## Data Sources
 
 - **On-chain contracts**: CSModule, CSAccounting, CSFeeDistributor, stETH

{csm_dashboard-0.2.1 → csm_dashboard-0.3.0}/README.md

@@ -11,8 +11,11 @@ Track your Lido Community Staking Module (CSM) validator earnings, excess bond,
 - Look up operator by Ethereum address (manager or rewards address) or operator ID
 - View current bond vs required bond (excess is claimable)
 - Track cumulative rewards and unclaimed amounts
+- Operator type detection (Permissionless, ICS/Legacy EA, etc.)
 - Detailed validator status from beacon chain (with `--detailed` flag)
 - APY metrics: reward APY, bond APY (stETH rebase), and net APY
+- Full distribution history with per-frame breakdown (with `--history` flag)
+- Withdrawal/claim history tracking (with `--withdrawals` flag)
 - JSON output for scripting and automation
 - CLI for quick terminal lookups
 - Web interface for browser-based monitoring
@@ -65,6 +68,7 @@ Available settings:
 - `BEACON_API_URL`: Beacon chain API (default: https://beaconcha.in/api/v1)
 - `BEACON_API_KEY`: Optional API key for beaconcha.in (higher rate limits)
 - `ETHERSCAN_API_KEY`: Optional API key for Etherscan (recommended for accurate historical data)
+- `THEGRAPH_API_KEY`: Optional API key for The Graph (enables historical Bond APY per distribution frame)
 - `CACHE_TTL_SECONDS`: Cache duration in seconds (default: 300)
 
 ## Usage
@@ -108,6 +112,8 @@ csm rewards [ADDRESS] [OPTIONS]
 | `ADDRESS` | | Ethereum address (required unless `--id` is provided) |
 | `--id` | `-i` | Operator ID (skips address lookup, faster) |
 | `--detailed` | `-d` | Include validator status from beacon chain and APY metrics |
+| `--history` | `-H` | Show all historical distribution frames with per-frame APY |
+| `--withdrawals` | `-w` | Include withdrawal/claim history |
 | `--json` | `-j` | Output as JSON (same format as API) |
 | `--rpc` | `-r` | Custom RPC URL |
 
@@ -123,6 +129,12 @@ csm rewards --id 42
 # Get detailed validator info and APY
 csm rewards --id 42 --detailed
 
+# Show full distribution history with Previous/Current/Lifetime columns
+csm rewards --id 42 --history
+
+# Include withdrawal history
+csm rewards --id 42 --withdrawals
+
 # JSON output for scripting
 csm rewards --id 42 --json
 
@@ -206,17 +218,16 @@ csm rewards --id 333 --json
   "operator_id": 333,
   "manager_address": "0x6ac683C503CF210CCF88193ec7ebDe2c993f63a4",
   "reward_address": "0x55915Cf2115c4D6e9085e94c8dAD710cabefef31",
+  "curve_id": 2,
+  "operator_type": "Permissionless",
   "rewards": {
-    "current_bond_eth": 651.5523536856277,
+    "current_bond_eth": 651.55,
     "required_bond_eth": 650.2,
-    "excess_bond_eth": 1.3523536856277778,
-    "cumulative_rewards_shares": 8973877501313655495,
-    "cumulative_rewards_eth": 10.9642938931415,
-    "distributed_shares": 7867435720490255061,
-    "distributed_eth": 9.61244204773546,
-    "unclaimed_shares": 1106441780823400434,
-    "unclaimed_eth": 1.3518518454060409,
-    "total_claimable_eth": 2.7042055310338187
+    "excess_bond_eth": 1.35,
+    "cumulative_rewards_eth": 10.96,
+    "distributed_eth": 9.61,
+    "unclaimed_eth": 1.35,
+    "total_claimable_eth": 2.70
   },
   "validators": {
     "total": 500,
@@ -231,44 +242,68 @@ With `--detailed`, additional fields are included:
 ```json
 {
   "operator_id": 333,
-  "...": "...",
+  "curve_id": 2,
+  "operator_type": "Permissionless",
   "validators": {
     "total": 500,
     "active": 500,
     "exited": 0,
     "by_status": {
-      "active": 100,
+      "active": 500,
       "pending": 0,
       "exiting": 0,
       "exited": 0,
-      "slashed": 0,
-      "unknown": 0
+      "slashed": 0
     }
   },
   "performance": {
     "avg_effectiveness": 98.5
   },
   "apy": {
-    "historical_reward_apy_28d": 2.21,
-    "historical_reward_apy_ltd": 2.03,
-    "bond_apy": 2.54,
-    "net_apy_28d": 4.75,
-    "net_apy_ltd": 4.57
+    "current_distribution_apy": 2.77,
+    "current_bond_apr": 2.56,
+    "net_apy_28d": 5.33,
+    "lifetime_reward_apy": 2.80,
+    "lifetime_bond_apy": 2.60,
+    "lifetime_net_apy": 5.40
   },
   "active_since": "2025-02-16T12:00:00"
 }
 ```
 
+With `--history`, you also get the full distribution frame history:
+
+```json
+{
+  "apy": {
+    "frames": [
+      {
+        "frame_number": 1,
+        "start_date": "2025-03-14T00:00:00",
+        "end_date": "2025-04-11T00:00:00",
+        "rewards_eth": 1.2345,
+        "validator_count": 500,
+        "duration_days": 28.0,
+        "apy": 2.85
+      }
+    ]
+  }
+}
+```
+
 ## API Endpoints
 
 - `GET /api/operator/{address_or_id}` - Get operator rewards data
   - Query param: `?detailed=true` for validator status and APY
+  - Query param: `?history=true` for all historical distribution frames
+  - Query param: `?withdrawals=true` for withdrawal/claim history
+- `GET /api/operator/{address_or_id}/strikes` - Get detailed validator strikes
 - `GET /api/operators` - List all operators with rewards
 - `GET /api/health` - Health check
 
 ## Understanding APY Metrics
 
-The dashboard shows three APY metrics when using the `--detailed` flag:
+The dashboard shows three APY metrics when using the `--detailed` or `--history` flags:
 
 | Metric | What It Means |
 |--------|---------------|
@@ -276,16 +311,34 @@ The dashboard shows three APY metrics when using the `--detailed` flag:
 | **Bond APY** | Automatic growth of your stETH bond from protocol rebasing (same for all operators) |
 | **NET APY** | Total return = Reward APY + Bond APY |
 
+### Display Modes
+
+- **`--detailed`**: Shows only the Current frame column (simpler view)
+- **`--history`**: Shows Previous, Current, and Lifetime columns with full distribution history
+
 ### How APY is Calculated
 
-**Reward APY** is calculated from actual reward distribution data published by Lido. Every ~28 days, Lido calculates how much each operator earned and publishes a "distribution frame" to IPFS (a decentralized file storage network). The dashboard fetches all these historical frames to calculate both 28-day and lifetime APY.
+**Reward APY** is calculated from actual reward distribution data published by Lido. Every ~28 days, Lido calculates how much each operator earned and publishes a "distribution frame" to IPFS (a decentralized file storage network). The dashboard fetches all these historical frames to calculate APY.
+
+- **Current APY**: Based on the most recent distribution frame (~28 days)
+- **Previous APY**: Based on the second-to-last distribution frame
+- **Lifetime APY**: Duration-weighted average of all frames, using **per-frame bond requirements** for accuracy
+
+The **Lifetime APY** calculation is particularly sophisticated: it uses each frame's actual validator count to determine the bond requirement for that period, then calculates a duration-weighted average. This produces accurate lifetime APY even for operators who have grown significantly over time.
+
+**Bond APY** represents the stETH rebase rate—the automatic growth of your bond due to Ethereum staking rewards. This rate is set by the Lido protocol and applies equally to all operators.
+
+> **Note**: With a Graph API key configured (`THEGRAPH_API_KEY`), Bond APY shows the actual historical stETH rate for each distribution frame. Without the API key, it falls back to the current rate (marked with an asterisk).
 
-- **28-Day APY**: Based on the most recent ~28 days of reward distributions
-- **Lifetime APY**: Based on all periods where you earned rewards (excludes ramp-up periods with no rewards to avoid misleadingly low numbers)
+### Operator Types
 
-**Bond APY** represents the stETH rebase rate—the automatic growth of your bond due to Ethereum staking rewards. This rate is set by the Lido protocol and applies equally to all operators. The dashboard shows the current 7-day average rate from Lido's API.
+The dashboard detects your operator type from the CSAccounting bond curve:
 
-> **Note**: Bond APY shows the current stETH rate for both 28-Day and Lifetime columns, as historical rates aren't readily available.
+| Type | Description |
+|------|-------------|
+| **Permissionless** | Standard operators (Curve 2, current default) |
+| **Permissionless (Legacy)** | Early permissionless operators (Curve 0, deprecated) |
+| **ICS/Legacy EA** | Incentivized Community Stakers / Early Adopters (Curve 1) |
 
 ### Why You Might Want an Etherscan API Key
 
@@ -304,6 +357,18 @@ The actual reward data lives on IPFS and is always accessible. However, to *disc
 
 The free tier allows 5 calls/second, which is plenty for this dashboard.
 
+### Why You Might Want a Graph API Key
+
+The Graph provides historical stETH APR data from the Lido subgraph. Without this API key, Bond APY calculations use the current rate for all periods, which is less accurate.
+
+**How to get one (free):**
+1. Go to [thegraph.com/studio](https://thegraph.com/studio/)
+2. Connect your wallet and create an account
+3. Go to "API Keys" and create a new key
+4. Add to your `.env` file: `THEGRAPH_API_KEY=your_key_here`
+
+The free tier includes 100,000 queries/month, which is plenty for this dashboard.
+
 ## Data Sources
 
 - **On-chain contracts**: CSModule, CSAccounting, CSFeeDistributor, stETH

{csm_dashboard-0.2.1 → csm_dashboard-0.3.0}/pyproject.toml

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

{csm_dashboard-0.2.1 → csm_dashboard-0.3.0}/src/abis/CSAccounting.json

@@ -33,5 +33,27 @@
     "outputs": [
       {"name": "", "type": "uint256"}
     ]
+  },
+  {
+    "name": "getBondCurve",
+    "type": "function",
+    "stateMutability": "view",
+    "inputs": [
+      {"name": "nodeOperatorId", "type": "uint256"}
+    ],
+    "outputs": [
+      {"name": "points", "type": "uint256[]"}
+    ]
+  },
+  {
+    "name": "getBondCurveId",
+    "type": "function",
+    "stateMutability": "view",
+    "inputs": [
+      {"name": "nodeOperatorId", "type": "uint256"}
+    ],
+    "outputs": [
+      {"name": "", "type": "uint256"}
+    ]
   }
 ]

{csm_dashboard-0.2.1 → csm_dashboard-0.3.0}/src/abis/stETH.json

@@ -38,5 +38,15 @@
     "outputs": [
       {"name": "", "type": "uint256"}
     ]
+  },
+  {
+    "name": "Transfer",
+    "type": "event",
+    "anonymous": false,
+    "inputs": [
+      {"indexed": true, "name": "from", "type": "address"},
+      {"indexed": true, "name": "to", "type": "address"},
+      {"indexed": false, "name": "value", "type": "uint256"}
+    ]
   }
 ]