Lido Ponder Indexer

Part of the RailPath open source ecosystem – building financial infrastructure that belongs to everyone.

Lido Ponder Indexer (Reference Implementation)

This repository contains the reference indexer implementation for the Lido Finance protocol, built with Ponder. It serves as a foundational data layer for the RailPath Risk Framework, providing granular, real-time data on staking positions, rewards, and protocol health.

Features

• Risk-Ready Data Models
  • Track user deposits & withdrawals with cryptographic precision.
  • Monitor active positions (balance, shares) for risk scoring.
  • Calculate lifetime metrics for behavioral analysis.
• Yield Analysis
  • Daily APR calculations from Oracle reports.
  • Share rate tracking (ETH per share) for asset valuation.
  • Historical yield data for VAR (Value at Risk) models.
• Auditability
  • Full transparency on all stETH transfers.
  • Immutable record of "SharesBurnt" (withdrawals).
• Safe Database Layer
  • Functional helpers (safeInsert, safeUpdate, etc.) provide centralized error handling.
  • Ensures resilience against duplicate key errors and transient DB issues.
• Pure ETH Tracking
  • This indexer is designed to be oracle-agnostic and tracks all value in native ETH.
  • USD calculations for TVL and Revenue should be computed externally (e.g., at the dashboard level) by applying historical price data to the indexed ETH values.
• GraphQL API
  • Standardized API for integrating with risk dashboards and compliance tools.

System Requirements

To ensure optimal performance and indexing speed:

• Ethereum RPC: Local node (retham/geth) or high-performance remote provider (Alchemy/Infura).
• Storage: High-speed SSD is required. Do not use HDDs.
• Database: PostgreSQL with approx. 10GB storage (Snapshot 2026).

Architecture

This project follows a Functional, Layered Architecture to ensure stability ("Bulletproof") and testability.

1. Core (src/core/)

Contains pure business logic without side effects.

• Pure Functions: Input -> Output. No database access.
• Test Coverage: 100% unit tested (see src/core/core.test.ts).
• Examples: extracting transaction hashes safely, normalizing timestamps.

2. Infrastructure (src/db/)

Safe repository layer that abstracts database interactions.

• Idempotency: handles onConflict strategies centrally.
• Error Barriers: Wraps operations in try-catch blocks to prevent indexer crashes due to malformed data.
• Atomic Operations: Manages supply updates via upserts.

3. Features (src/features/)

Feature-specific orchestration logic.

• Deposits: Handles user deposits and stETH minting.
• Rewards: Processes daily rebasing and APR tracking.
• Transfers: Manages balance updates and position tracking.
• Withdrawals: Tracks share burning and ETH claim logic.

Quick Start

1. Install Dependencies

   npm install

2. Configure Environment Copy .env.example to .env and add your Mainnet RPC URL.

   cp .env.example .env
   # Edit PONDER_RPC_URL_1=...

3. Run Dev Server

   npm run dev

   Open http://localhost:42069/graphql

Docker

docker-compose up -d

Project Structure

railpath-lido-indexer/
├── src/               
│   ├── core/          # Pure Business Logic (Factories, Calculators)
│   ├── db/            # Safe Database Layer (Functional Helpers)
│   ├── features/      # Event Handlers (Deposits, Rewards, etc.)
│   ├── index.ts       # Entry Point
├── abis/              # Smart Contract ABIs
├── ponder.schema.ts   # Database Schema (Risk Entities)
├── ponder.config.ts   # Chain Configuration
└── tests/             # Unit & Integration Tests

Analytics & Metrics

We provide pre-built GraphQL queries for common risk metrics in metrics.graphql:

• Protocol Health (TVL, Staker Count)
• Daily APY & Volatility
• Whale Tracking (Top Stakers)
• Net Flow Analysis

License

MIT. Part of the RailPath Open Source Initiative.