Solana Modular Execution Engine

A high-performance, async-first execution framework for Solana, engineered with a focus on modularity, type safety, and reliability.

Architectural Highlights

This project demonstrates advanced Rust patterns applied to blockchain execution systems:

Pattern	Implementation
Trait-Based Provider Pattern	Fully decoupled Strategy, DexClient, WalletSelector, and Notifier traits
Type-Safe State Machine	ExecutionState enum with validated transitions prevents invalid states
Circuit Breaker Middleware	Automatic failure detection, recovery, and slippage protection
Async Architecture	Cancellation-safe tokio::select! with broadcast shutdown
Zero-Cost Abstractions	Generic engine with compile-time monomorphization

Technical Stack

• Runtime: tokio (multi-threaded async)
• Serialization: serde + toml (type-safe configuration)
• Error Handling: thiserror (structured error hierarchy)
• Observability: tracing with structured logging
• Blockchain: solana-sdk 2.2, Jupiter aggregator

Key Components

Circuit Breaker

The DexClient is wrapped in middleware that monitors failure rates and automatically transitions between Closed, Open, and HalfOpen states:

let client = CircuitBreaker::new(jupiter_client, CircuitBreakerConfig::strict());
// Automatically protects against cascading failures
let quote = client.get_quote(input, output, amount, slippage).await?;

State Machine

Engine lifecycle is enforced at the type level:

Idle → Initializing → Running → Stopping → Stopped
                  ↘         ↘
                   → Paused  → Error

Invalid transitions (e.g., Running → Idle) are rejected at runtime with StateTransitionError.

Strategy Trait

Pluggable execution strategies implement a simple async interface:

#[async_trait]
pub trait Strategy: Send + Sync {
    fn name(&self) -> &str;
    fn has_next(&self) -> bool;
    async fn next_order(&mut self) -> Result<Option<Order>>;
    async fn mark_executed(&mut self, id: &str, success: bool) -> Result<()>;
}

Project Structure

solana-execution-engine/
├── engine/                 # Core library crate
│   └── src/
│       ├── execution/      # Engine + state machine + order types
│       ├── strategy/       # Strategy trait + PeriodicStrategy
│       ├── dex/            # DexClient trait + Jupiter + Circuit Breaker
│       ├── wallet/         # WalletPool + selection strategies
│       └── notify/         # Notifier trait + Discord/Stdout
└── cli/                    # clap-based CLI

CLI Commands

# Validate configuration
cargo run -- validate --config config.example.toml --wallets wallets.example.toml

# Run in dry-run mode (no real transactions)
cargo run -- run --dry-run --config config.example.toml

# Show wallet balances
cargo run -- balances --config config.example.toml

# Show engine status
cargo run -- status

Design Decisions

See ARCHITECTURE.md for detailed design rationale.

License

MIT