botcore

A flexible and efficient bot engine framework for building event-driven bots in Rust.

Overview

botcore is a high-performance, type-safe framework for building event-driven bots in Rust. It provides a modular architecture that makes it easy to create, test, and maintain bot applications that can react to various events in real-time.

Features

• 🚀 High Performance

  • Built on top of Tokio for maximum concurrency
  • Efficient event processing pipeline
  • Configurable channel capacities for backpressure control

• 🔧 Modular Architecture

  • Plug-and-play components
  • Easy to extend and customize
  • Clear separation of concerns

• 📊 Observability

  • Built-in Prometheus metrics
  • Performance monitoring
  • Error tracking and reporting

• 🛠️ Developer Experience

  • Type-safe API design
  • Comprehensive documentation
  • Example implementations
  • Clear error messages

• 🔄 Event Processing

  • Flexible event collection
  • Customizable processing strategies
  • Reliable action execution
  • State management utilities

Installation

Add botcore to your project using cargo:

cargo add botcore --features metrics

Architecture

The framework is built around three core components:

1. Collectors

Event sources that feed data into your bot:

• Blockchain event listeners
• WebSocket API clients
• Database change streams
• Message queues
• File system watchers

2. Strategies

Processing logic that determines bot behavior:

• State management
• Decision making
• Event filtering
• Action generation
• Error handling

3. Executors

Action handlers that effect changes:

• Transaction submission
• API calls
• Database operations
• Notifications
• External system integration

Quick Start

use botcore::engine::Engine;
use botcore::types::{Collector, Strategy, Executor};
use botcore::Result;

// 1. Define your types
#[derive(Debug, Clone)]
struct MyEvent {
    data: String,
}

#[derive(Debug, Clone)]
struct MyAction {
    command: String,
}

// 2. Implement a collector
#[async_trait]
impl Collector<MyEvent> for MyCollector {
    async fn get_event_stream(&self) -> Result<CollectorStream<'_, MyEvent>> {
        // Return your event stream
    }
}

// 3. Implement a strategy
#[async_trait]
impl Strategy<MyEvent, MyAction> for MyStrategy {
    async fn process_event(&mut self, event: MyEvent) -> Vec<MyAction> {
        // Process events and return actions
    }
}

// 4. Implement an executor
#[async_trait]
impl Executor<MyAction> for MyExecutor {
    async fn execute(&self, action: MyAction) -> Result<()> {
        // Execute actions
        Ok(())
    }
}

// 5. Run the engine
#[tokio::main]
async fn main() -> Result<()> {
    let mut engine = Engine::new()
        .with_event_channel_capacity(1024)
        .with_action_channel_capacity(1024);

    engine.add_collector(Box::new(MyCollector));
    engine.add_strategy(Box::new(MyStrategy));
    engine.add_executor(Box::new(MyExecutor));

    let join_set = engine.run().await?;
    join_set.await;
    Ok(())
}

Examples

The examples/ directory contains working implementations:

• block_trader.rs: A bot that executes trades based on blockchain events

  cargo run --example block_trader
  

Monitoring

botcore automatically collects the following Prometheus metrics:

Configuration

The engine can be configured through builder methods:

let engine = Engine::new()
    .with_event_channel_capacity(1024)
    .with_action_channel_capacity(1024)
    .with_metrics_enabled(true);

Error Handling

botcore provides a comprehensive error type system:

• Clear error messages
• Error categorization
• Error context preservation
• Recovery strategies

Best Practices

1. Event Design

   • Keep events small and focused
   • Include necessary context
   • Use appropriate serialization

2. Strategy Implementation

   • Handle state carefully
   • Implement proper error handling
   • Keep processing logic modular

3. Execution

   • Implement retries for transient failures
   • Handle rate limiting
   • Log important state changes

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code style
• Pull request process
• Development setup
• Testing requirements

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation
• Issue Tracker
• Discussions