velora-core

Core types, errors, and utilities for the Velora HFT platform

Overview

velora-core is the foundation crate of the Velora ecosystem. It provides fundamental types, error handling, and utilities used by all other Velora crates.

Purpose

• Provide common data types for trading (Price, Volume, Order, Trade, etc.)
• Define market data structures (Tick, Candle, OrderBook)
• Centralize error handling
• Manage configuration
• Ensure type safety for numeric operations

Key Features

Core Trading Types

• Price & Volume: Ordered floating-point types that can be compared and sorted
• Symbol: Type-safe trading pair representation (e.g., "BTC/USD")
• Side: Buy/Sell enumeration
• OrderType: Market, Limit, StopLimit, StopMarket

Order & Trade Management

• Order: Complete order structure with status tracking
• Trade: Executed trade information
• Position: Current position with P&L calculations
• Balance: Account balance information

Market Data

• Tick: Real-time price update
• Candle: OHLCV candlestick data
• OrderBook: Bid/ask depth with price levels
• Interval: Time intervals for candles (1m, 5m, 1h, etc.)

Error Handling

• VeloraError: Comprehensive error enumeration
• Result: Type alias for Result<T, VeloraError>
• Conversions from common error types

Configuration

• VeloraConfig: Main configuration structure
• ExchangeConfig: Exchange connection settings
• EngineConfig: Engine parameters
• RiskConfig: Risk management settings

Dependencies

This crate has minimal dependencies:

• serde - Serialization/deserialization
• chrono - Date and time handling
• ordered-float - Ordered floating-point types
• thiserror - Error derivation
• uuid - Unique identifiers
• config - Configuration management

Design Principles

Type Safety

All numeric values use OrderedFloat<f64> to ensure they can be compared and sorted correctly. This prevents NaN-related bugs in trading logic.

Zero Dependencies on Other Velora Crates

This crate has no dependencies on other Velora crates, making it the foundation of the dependency graph.

Simplicity

Types are kept simple and focused. Complex logic belongs in higher-level crates.

Serializability

All types implement Serialize and Deserialize for easy persistence and transmission.

Module Structure

velora-core/
├── src/
│   ├── lib.rs         # Public API exports
│   ├── types.rs       # Core data types
│   ├── errors.rs      # Error types
│   └── config.rs      # Configuration

Public API (Planned)

Types Module

// Core types
pub type Price = OrderedFloat<f64>;
pub type Volume = OrderedFloat<f64>;
pub struct Symbol(String);
pub enum Side { Buy, Sell }
pub enum OrderType { Market, Limit, StopLimit, StopMarket }
pub enum OrderStatus { Pending, Open, PartiallyFilled, Filled, Cancelled, Rejected, Expired }

// Trading structures
pub struct Order { /* ... */ }
pub struct Trade { /* ... */ }
pub struct Position { /* ... */ }
pub struct Balance { /* ... */ }

// Market data
pub struct Tick { /* ... */ }
pub struct Candle { /* ... */ }
pub struct OrderBook { /* ... */ }
pub struct BookLevel { /* ... */ }
pub enum Interval { Second1, Minute1, Minute5, /* ... */ }

Errors Module

pub enum VeloraError {
    DataError(String),
    ExchangeError(String),
    OrderError(String),
    StrategyError(String),
    RiskLimitExceeded(String),
    ConfigError(String),
    // ... more variants
}

pub type Result<T> = std::result::Result<T, VeloraError>;

Config Module

pub struct VeloraConfig {
    pub exchanges: HashMap<String, ExchangeConfig>,
    pub engine: EngineConfig,
    pub risk: RiskConfig,
    pub logging: LoggingConfig,
}

pub struct ExchangeConfig { /* ... */ }
pub struct EngineConfig { /* ... */ }
pub struct RiskConfig { /* ... */ }

Usage Example (Future)

use velora_core::*;

// Create a new order
let order = Order::new_limit(
    Symbol::new("BTC/USD"),
    Side::Buy,
    Price::from(50000.0),
    Volume::from(0.1),
);

// Work with market data
let tick = Tick {
    symbol: Symbol::new("BTC/USD"),
    price: 50000.0.into(),
    volume: 1.0.into(),
    timestamp: Utc::now(),
};

// Calculate mid price from order book
let mid_price = orderbook.mid_price();

Testing Strategy

Unit Tests

• Test all type conversions
• Verify numeric ordering
• Test serialization/deserialization
• Validate error conversions

Property-Based Tests

• Use proptest to verify invariants
• Ensure price/volume operations are correct
• Validate position calculations

Performance Considerations

Zero-Copy Operations

Where possible, types use references and borrowing to avoid unnecessary copies.

Efficient Representations

• Symbol uses String internally but provides efficient comparison
• OrderedFloat has the same size as f64
• Enums use efficient representations

Thread Safety

All core types are Send and Sync where appropriate, enabling safe concurrent use.

Versioning

This crate follows semantic versioning. Breaking changes to core types will result in a major version bump.

Status

🚧 In Planning - This crate is currently in the planning phase.

Next Steps

1. Implement core types in types.rs
2. Implement error handling in errors.rs
3. Implement configuration in config.rs
4. Write comprehensive tests
5. Generate documentation with examples
6. Publish to crates.io

Contributing

Contributions are welcome! Please ensure:

• All types are properly documented
• Tests are included for new functionality
• Breaking changes are clearly marked
• Serialization compatibility is maintained

License

MIT