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

• Node.js v22.6.0 (see .nvmrc)
• Yarn
• PostgreSQL database

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.