Skip to content

README.md

Latest commit

 

History

History
214 lines (152 loc) · 5.59 KB

README.md

File metadata and controls

214 lines (152 loc) · 5.59 KB

Balmy Indexer

A custom blockchain indexing service for Balmy Finance that tracks and processes on-chain events across multiple EVM chains.

Overview

The Balmy Indexer is a flexible, high-performance indexing solution that discovers, processes, and stores blockchain events to power Balmy's user-facing applications. It provides fast access to historical data including DCA positions, swaps, token transfers, approvals, and more.

Unlike general-purpose solutions like The Graph, this indexer is optimized for Balmy's specific needs with support for:

  • Account-based event tracking (monitoring specific wallets)
  • Off-chain data enrichment (e.g., historical token prices)
  • Custom processing logic per event type
  • Low-latency updates for real-time user experiences
  • Multi-instance coordination for high availability

Architecture

The indexer operates in three stages:

1. Detection

Detects relevant blockchain events, transactions, or scheduled intervals through multiple sources:

  • Event Detection: Monitors smart contract events via RPC polling
  • Transaction Detection: Tracks specific transaction types
  • Transfer Detection: Monitors token transfers using services like Alchemy or Moralis
  • Scheduled Detection: Triggers based on time intervals

2. Collection

Collects additional contextual data needed for processing:

  • Historical token prices at transaction time
  • Token metadata (symbols, decimals, names)
  • Block timestamps and confirmations
  • Related transaction data

3. Processing

Processes the enriched data and stores it in PostgreSQL:

  • Decodes and validates event data
  • Applies business logic specific to each event type
  • Stores processed data for API consumption
  • Maintains data consistency and integrity

Indexed Units

The indexer currently tracks the following event types:

  • DCA - Dollar Cost Averaging positions and swaps
  • Earn - Vault positions, deposits, withdrawals, and delayed withdrawals
  • Aggregator Swaps - Meta aggregator swap executions
  • ERC20 Transfers - Token transfer events for monitored accounts
  • ERC20 Approvals - Token approval events for monitored accounts
  • Native Transfers - Native currency transfers for monitored accounts
  • Wallets in Chains - Daily active wallet metrics
  • Chainlink Feed Registry - Price feed data

Requirements

Getting Started

Installation

Install dependencies:

yarn install

Configuration

Copy the default environment variables:

cp .env.default .env

Edit .env with your configuration:

  • Database connection details
  • RPC endpoints for each chain
  • API keys for external services (Alchemy, Moralis, etc.)
  • Price feed configurations

Build

Compile the TypeScript project:

yarn build

Running

Start the indexer:

yarn start

For development with auto-reload:

yarn dev

Or with nodemon:

yarn watch

Development

Code Quality

Check code formatting:

yarn lint:check

Auto-fix formatting issues:

yarn lint:fix

Testing

Run all tests:

yarn test

Run only unit tests:

yarn test:unit

Run only integration tests:

yarn test:integration

Run specific tests matching a pattern:

yarn test -t 'pattern'

Git Hooks

This project uses Husky for git hooks:

  • Pre-commit: Runs prettier and sorts package.json
  • Commit-msg: Validates commit messages follow conventional commits

Project Structure

src/
├── balmy/              # Balmy-specific implementation
│   ├── start.ts        # Application entry point
│   ├── config.ts       # Indexer configuration
│   ├── units/          # Indexing units (DCA, Earn, etc.)
│   └── http-server.ts  # HTTP API server
├── components/         # Core components
│   ├── detectors/      # Event, transaction, and transfer detection
│   ├── rpcs/           # RPC client management
│   ├── database/       # Database layer
│   ├── price-fetching/ # Price data collection
│   └── metadata/       # Token metadata fetching
├── config/             # Configuration and builders
│   ├── built-in/       # Built-in handlers and units
│   └── build/          # Component builders
├── indexing/           # Core indexing logic
│   ├── indexer.ts      # Main indexer orchestration
│   └── definitions/    # Type definitions
└── utils/              # Shared utilities

High Availability

The indexer supports multi-instance deployment with automatic coordination:

  • Multiple instances can run simultaneously
  • Only one instance actively indexes at a time
  • Automatic failover if the active instance stops
  • All instances serve the HTTP API

Technology Stack

  • Runtime: Node.js with TypeScript
  • Database: PostgreSQL
  • Blockchain: viem for Ethereum interactions
  • SDK: @balmy/sdk for Balmy protocol integration
  • Framework: Express.js for HTTP API
  • Testing: Jest
  • External Services: Alchemy, Moralis for enhanced transfer detection

Contributing

Contributions are welcome! Please ensure:

  1. Code follows the existing style (enforced by Prettier)
  2. Tests pass (yarn test)
  3. Commit messages follow conventional commits format

License

See the LICENSE file for details.