Liquidation Indexer

A high-performance, real-time indexer for DeFi liquidation events on Solana. Monitors Drift and Kamino protocols with sub-second processing and multi-channel notifications.

Overview

Real-time blockchain indexer that detects, parses, and processes liquidation events across multiple DeFi protocols on Solana.

Key Features: - ⚡ <500ms latency from blockchain to notification - 🔄 1000+ events/second processing capacity - 🎯 Multi-protocol support (Drift, Kamino + extensible) - 📢 Multiple notifications (Webhooks, Discord, Telegram, Email) - 📊 PostgreSQL storage with full audit trail - 🔍 Health monitoring and position tracking

Architecture

System Flow

graph TB
    BC[Solana Blockchain] --> YS[Yellowstone gRPC]
    YS --> SF[Stream Filter]
    SF --> TQ[Transaction Queue]
    TQ --> TD[Transaction Decoder]
    TD --> PP{Protocol Parser}

    PP --> DP[Drift Parser]
    PP --> KP[Kamino Parser]
    PP --> GP[Generic Parser]

    DP --> EV[Event Validator]
    KP --> EV
    GP --> EV

    EV --> EH[Event Handler]
    EH --> DB[(PostgreSQL)]
    EH --> AN[Alert Notifier]

    AN --> WH[Webhooks]
    AN --> DS[Discord]
    AN --> TG[Telegram]

Protocol Detection Flow

graph TB
    TI[Raw Transaction] --> PD{Protocol Detection}

    PD -->|Drift ID| DP[Drift Parser]
    PD -->|Kamino ID| KP[Kamino Parser] 
    PD -->|Unknown| GP[Generic Parser]

    subgraph "Drift Processing"
        DP --> SL[Spot Liquidation]
        DP --> PL[Perp Liquidation]
        SL --> HRC[Health Ratio Calc]
        PL --> HRC
    end

    subgraph "Kamino Processing" 
        KP --> LV1[Lending V1/V2]
        LV1 --> OP[Obligation Parse]
    end

    HRC --> ON[Normalized Event]
    OP --> ON
    GP --> ON

    ON --> V[Validator] --> OUT[Validated Event]

Quick Start

Prerequisites

• Rust 1.70+
• PostgreSQL 13+
• Yellowstone gRPC access

Installation

1. Clone and build

git clone https://github.com/your-org/liquidation-indexer
cd liquidation-indexer
cargo build --release

1. Setup database

createdb liquidation_indexer
psql liquidation_indexer -f migrations/001_initial.sql

1. Configure

cp config.example.toml config.toml
# Edit config.toml with your settings

1. Run

export DATABASE_URL="postgresql://user:pass@localhost/liquidation_indexer"
export GRPC_ENDPOINT="https://your-grpc-endpoint.com"
export GRPC_X_TOKEN="your_token"

cargo run --release

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

Configuration

Essential Settings

[database]
url = "postgresql://user:pass@localhost/liquidation_indexer"
max_connections = 20

[grpc]
endpoint = "https://api.mainnet-beta.solana.com"
x_token = "your_grpc_token"

[notifications]
webhook_urls = ["https://your-webhook.com/liquidation"]
discord_webhook_url = "https://discord.com/api/webhooks/..."
timeout_seconds = 30

[processing]
max_concurrent_events = 50

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection	✅
GRPC_ENDPOINT	Yellowstone gRPC endpoint	✅
GRPC_X_TOKEN	gRPC auth token	✅
WEBHOOK_URLS	Comma-separated webhook URLs	❌

Protocol Support

Drift Protocol

• Spot and perpetual liquidations
• Health ratio calculations
• Market data extraction
• Instructions: liquidate_spot, liquidate_perp

Kamino Protocol

• Lending V1 & V2 support
• Obligation parsing
• Collateral extraction
• Instructions: liquidate_obligation_and_redeem_reserve_collateral

Adding New Protocols

1. Create parser in parsers/new_protocol/
2. Implement ProtocolParser trait
3. Register in main parser map

API & Webhooks

Webhook Payload

{
  "event_type": "liquidation",
  "timestamp": "2024-01-15T10:30:45Z",
  "liquidation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "signature": "5VfYm...X8bK",
    "protocol": "drift",
    "liquidator": "7xKXt...9sZ2",
    "liquidatee": "3mEr4...Kd9P",
    "asset_symbol": "SOL",
    "liquidated_amount": 1500.75,
    "liquidation_fee": 15.00,
    "health_ratio_before": 0.85,
    "health_ratio_after": 1.20
  }
}

Health Endpoints

• GET /health - Overall system health
• GET /health/database - Database status
• GET /health/grpc - gRPC connection

Monitoring

Prometheus Metrics

liquidation_events_total{protocol, status}
liquidation_events_processing_duration_seconds
database_connections_active
notifications_sent_total{type, status}

Performance Benchmarks

Metric	Value
Event Processing Rate	1,200+ events/sec
Average Latency	<400ms
Database Write Rate	800+ inserts/sec
Memory Usage	<200MB

Development

Testing

# Unit tests
cargo test

# Integration tests (requires database)
cargo test --features integration-tests

# Code quality
cargo fmt && cargo clippy -- -D warnings

Project Structure

src/
├── main.rs              # Application entry
├── config.rs            # Configuration
├── database/            # Database operations
├── events/              # Event processing
├── notifications/       # Alert system
parsers/
├── drift_protocol/      # Drift parser
├── kamino_protocol/     # Kamino parser
migrations/
├── 001_initial.sql      # Database schema

Troubleshooting

Common Issues

Database Connection

pg_isready -h localhost -p 5432
psql $DATABASE_URL -c "SELECT 1;"

gRPC Issues

curl -I $GRPC_ENDPOINT
echo $GRPC_X_TOKEN

High Memory Usage

export RUST_MIN_STACK=4194304

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make changes and add tests
4. Run cargo fmt && cargo clippy && cargo test
5. Commit (git commit -m 'feat: add amazing feature')
6. Push and create Pull Request

License

MIT License - see LICENSE file.