Chain Cast

A powerful open-source tool designed to listen to and recover events from Ethereum smart contracts deployed on any EVM chain. By seamlessly integrating with EVM chains, Chain Cast provides developers and businesses with the ability to extract and process valuable event data in a reliable and efficient manner.

Open Source Project: Chain Cast is developed and maintained by LayerX Labs. For commercial licensing, please contact LayerX Labs.

🌟 Features

Event Listening and Recovery

• Universal Event Support: Process any event from any smart contract—not limited to ERC-20 transfers. Simply provide your contract's ABI when creating a Cast, and ChainCast will monitor all specified events
• Real-time Event Monitoring: Establishes connections with smart contracts and monitors their event logs in real-time
• Automatic Recovery: Automatically recovers missed events during network interruptions or downtime
• Robust Data Flow: Ensures uninterrupted data flow with comprehensive error handling

Programmable Event Processing Pipeline

• YAML-Based DSL: Write event processing pipelines using a simple, declarative YAML syntax
• Customizable Processing: Define customized event processing pipelines tailored to your specific needs
• Flexible Configuration: Programmable configurations for defining sequences of processors and actions
• Extensible Framework: Support for data transformation, filtering, enrichment, aggregation, and custom operations
• Built-in Compiler: Validate and compile DSL pipelines with the castc CLI tool

Extensible Instructions Architecture

Chain Cast's virtual machine is built around a modular instructions architecture that allows for easy extension and customization:

Core Instruction Types

• Data Transformations: String manipulation, number formatting, object restructuring, array operations
• Conditional Logic: Complex filtering and branching based on event data
• External Integrations: Webhooks, message queues, databases, analytics platforms
• Data Processing: Aggregation, enrichment, validation, and custom business logic

Built-in Instructions

• transform-string: Text manipulation (capitalize, lowercase, camelize, etc.)
• transform-number: Numeric operations and formatting
• transform-object: Object restructuring and field mapping
• transform-array: Array operations and filtering
• transform-template: Template-based data transformation
• condition: Conditional logic and branching
• filter-events: Event filtering based on criteria
• webhook: HTTP webhook integration
• bullmq: Message queue integration
• elastic-search: Elasticsearch data indexing
• spreadsheet: Google Sheets integration
• debug: Development and debugging utilities

Custom Instruction Development

The instruction system is designed for extensibility:

export class CustomInstruction implements Instruction {
  INSTRUCTION_NAME = 'custom-instruction';

  validateArgs(args: InstructionArgs): boolean {
    // Validate input arguments using Zod schemas
    return true;
  }

  name(): string {
    return this.INSTRUCTION_NAME;
  }

  getArgsSchema(): typeof ArgsTypeSchema {
    return ArgsTypeSchema;
  }

  async onAction(vm: VirtualMachine): Promise<void> {
    // Implement custom processing logic
    // Access event data via vm.getGlobalVariable('event')
    // Access cast configuration via vm.getGlobalVariable('cast')
  }
}

Integration Capabilities

• External APIs: Connect to any REST API or GraphQL endpoint
• Message Queues: Integrate with Redis, RabbitMQ, Apache Kafka
• Databases: Direct database operations and data persistence
• Analytics: Send data to analytics platforms and monitoring systems
• Notifications: Real-time alerts and notifications
• Custom Logic: Implement any business logic or data processing

Seamless Integration

• External System Integration: Forward processed events to databases, message queues, analytics platforms, or any desired destinations
• Real-time Notifications: Create real-time notifications and triggers for downstream actions
• Analytics Support: Generate reports and drive decision-making processes

🚀 Quick Start

⚡ Powered by Bun: Chain Cast runs on Bun runtime for faster startup times, native TypeScript execution, and improved performance. No build step required!

Prerequisites

• Bun: 1.0.0 or above (Install Bun)
• PostgreSQL: Local database recommended for development
• Redis: For queue management (optional for development)

Installation

1. Clone the repository

   git clone https://github.com/layerx-labs/chain-cast.git
   cd chain-cast

2. Install dependencies

   bun install

3. Set up environment variables

   cp env.example .env.local

   Configure your .env.local file:

   DATABASE_URL=postgresql://username:password@localhost:5432/chaincast?schema=public
   LOG_LEVEL=debug
   SILENT=false
   LOG_TO_FILE=false
   CHAIN_CAST_API_PORT=4400

4. Initialize the database

   bunx prisma migrate reset

5. Start the development environment

   bun run dev

   This will start:

   • API server at http://localhost:4400/api/graphql

🎯 Getting Started

Ready to monitor real blockchain events? Follow our comprehensive guide:

📖 Getting Started Guide

This guide walks you through monitoring $LX token transfers on Ethereum mainnet, demonstrating how ChainCast works with production chains. You'll learn to:

• Set up ChainCast with Alchemy RPC
• Create event processing programs
• Monitor live token transfers in real-time
• Use the GraphQL API to manage casts

🔧 Writing Custom Pipelines

Chain Cast features a powerful YAML-based DSL (Domain-Specific Language) that allows you to create custom event processing pipelines without writing code. Pipelines are fully programmable and can include:

• Event filtering - Process only specific events
• Data transformations - Manipulate strings, numbers, objects, and arrays
• Conditional logic - Branch execution based on event data
• External integrations - Send data to webhooks, queues, databases, and more

Example Pipeline

version: "1.0"
name: "High Value Transfer Monitor"
description: "Alert on large token transfers"

program:
  - filter-events:
      events: ["Transfer"]

  - set:
      variable: threshold
      value: 1000000000000000000000  # 1000 tokens

  - condition:
      when:
        all:
          - variable: event.returnValues.value
            operator: ">"
            compareTo: threshold
      then: branch_0
      else: branch_1
      branches:
        branch_0:
          - webhook:
              url: "https://api.example.com/alerts"
              body: event
        branch_1:
          - debug:
              variables: [event]

Compile and Deploy

# Validate your pipeline
bun run castc validate my-pipeline.yaml

# Compile to base64 for the ChainCast API
bun run castc compile my-pipeline.yaml --base64

For the complete DSL reference and more examples, see the DSL Programming Guide.

📚 Documentation

• DSL Programming Guide - Learn how to write custom event processing pipelines
• API Documentation
• Contributing Guidelines
• Code of Conduct

🧪 Testing

# Run all tests
bun test

# Run tests with coverage
bun test --coverage

🏗️ Development

Available Scripts

• bun run dev: Start application in development mode with hot reload
• bun run dev:debug: Start application with debug mode (inspect on port 4321)
• bun run build: Install dependencies and generate Prisma client
• bun run start: Start the production server
• bun run lint: Lint code with Biome
• bun run lint:fix: Fix lint issues automatically
• bun run format: Format code with Biome
• bun run check: Run all Biome checks (lint + format)
• bun run check:fix: Fix all Biome issues
• bun run db:reset: Reset the database
• bun run db:migrate: Run database migrations
• bun run db:push: Push Prisma schema to database

Technology Stack

• Bun: Fast JavaScript runtime and package manager
• Prisma 4: ORM for database interactions
• viem: TypeScript-first Ethereum library for blockchain interactions
• PostgreSQL: Primary database
• GraphQL Yoga: GraphQL server
• Biome: Fast linting and formatting (replaces ESLint + Prettier)
• Bun Test: Built-in testing framework
• TypeScript: Type-safe JavaScript (runs natively without compilation)

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on how to submit pull requests, report issues, and contribute to the project.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Ensure all tests pass: bun test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the MIT License for open source and non-commercial use. Commercial use requires a license from LayerX Labs. For commercial licensing inquiries, please contact gm@layerx.xyz.

License Types

• MIT License: For open source and non-commercial use
• Commercial License: Required for commercial use - contact LayerX Labs

See the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Contact: gm@layerx.xyz

🙏 Acknowledgments

• Built with ❤️ by the LayerX Labs team
• Thanks to all our contributors

---

Made with ❤️ by LayerX Labs