Skip to main content

Crate of_core

Crate of_core 

Source
Expand description

§of_core

of_core defines the canonical data model and analytics primitives used across the Orderflow stack. It is provider-agnostic and intentionally lightweight so every binding (C, Python, Java) can rely on the same normalized semantics.

§What This Crate Contains

§New In 0.4.0

0.4.0 keeps the established of_core analytics contracts stable while the larger Orderflow release adds execution and OMS capabilities around them. Existing users of AnalyticsAccumulator, AnalyticsSnapshot, BookSnapshot, candle snapshots, quality flags, and tickbar aggregation do not need to rename or rewrite code.

What changes for of_core users:

  • of_core remains the canonical market-data and analytics schema for the project.
  • execution types intentionally live in the new of_execution_core crate, so order-management concerns do not pollute the market-data accumulator.
  • strategies can now combine of_core analytics with of_execution simulated order flow, but the integration is at the application layer.
  • tickbar APIs remain optional behind the tickbar feature and are still additive.
  • DataQualityFlags remain the bridge between market-data correctness and strategy/execution gating.

Version policy:

  • established analytics crates publish as 0.4.0;
  • new execution crates publish as 0.1.0;
  • this split is intentional because execution has a newer public trait surface while of_core continues its existing compatibility line.

§Public API Inventory

Public types:

Public DataQualityFlags methods:

Public AnalyticsAccumulator methods:

§Design Principles

  • Deterministic arithmetic: prices and sizes are integer values, avoiding float drift in replay/backtests.
  • Stable schema: types are designed for cross-language transport and long-lived storage.
  • Minimal dependencies: this crate stays small so it can be embedded broadly.

§Type Semantics Reference

§Market identity and direction

  • SymbolId is the canonical identity key used everywhere in the project. venue should be the normalized venue name and symbol should remain stable for the life of a stream.
  • Side uses Bid and Ask for both book updates and trade aggressor direction.
  • BookAction uses Upsert for insert-or-replace semantics and Delete for level removal.

§Book event types

  • BookUpdate represents a single level mutation. level is the depth index from top of book. price and size are integer-normalized values. sequence, ts_exchange_ns, and ts_recv_ns preserve replay ordering and latency analysis.
  • BookLevel is the materialized view of one price level after runtime consolidation.
  • BookSnapshot is the full reconstructed book for one symbol at one point in time. bids and asks are level-ordered arrays. last_sequence is the sequence of the last applied update. ts_exchange_ns and ts_recv_ns are copied from that last applied update.

§Trade event types

  • TradePrint represents one normalized trade. price and size are integer-normalized. aggressor_side is the trade direction used by the analytics engine. sequence may be zero when a source does not provide a venue sequence.

§Analytics and signal output types

  • AnalyticsSnapshot is the base session analytics payload. It includes directional volume, delta, cumulative delta, POC, value area, and the active quality flags.
  • DerivedAnalyticsSnapshot adds additive session totals that were intentionally kept out of the original analytics payload so older consumers would not break.
  • SessionCandleSnapshot is a session-wide candle view derived from ingested trades.
  • IntervalCandleSnapshot is a rolling-window candle view computed on demand from recent trades for a caller-supplied window_ns.
  • SignalState is the stable directional state machine used across the runtime and bindings.
  • SignalSnapshot packages state, confidence, reason text, and quality flags for downstream consumers.

§AnalyticsAccumulator Contract

AnalyticsAccumulator is session-oriented.

Important behavior:

  • No book data is required for AnalyticsAccumulator; it is trade-driven.
  • All price and size arithmetic uses integer math at ingest time and converts only where a derived floating result is needed, such as vwap.
  • point_of_control is volume-based, not quote-based.
  • Value area fields are derived from traded-volume distribution, not full order-book depth.

§Quick Start

use of_core::{AnalyticsAccumulator, Side, SymbolId, TradePrint};

let symbol = SymbolId {
    venue: "CME".to_string(),
    symbol: "ESM6".to_string(),
};

let mut acc = AnalyticsAccumulator::default();
acc.on_trade(&TradePrint {
    symbol,
    price: 505_000,
    size: 10,
    aggressor_side: Side::Ask,
    sequence: 1,
    ts_exchange_ns: 1,
    ts_recv_ns: 2,
});

let snap = acc.snapshot();
assert_eq!(snap.buy_volume, 10);
assert_eq!(snap.delta, 10);

§Quality Flags

DataQualityFlags is a bitset used to express data-health issues such as stale feed, sequence gaps, and out-of-order events. Signals and runtime gating can use these flags to block unsafe decisions.

use of_core::DataQualityFlags;

let q = DataQualityFlags::STALE_FEED | DataQualityFlags::SEQUENCE_GAP;
assert!(q.intersects(DataQualityFlags::STALE_FEED));
assert_eq!(q.bits() & DataQualityFlags::SEQUENCE_GAP.bits(), DataQualityFlags::SEQUENCE_GAP.bits());

§Analytics Model Notes

  • delta tracks current session directional imbalance.
  • cumulative_delta retains directional accumulation over time.
  • point_of_control is computed as highest-volume price level.
  • value_area_low / value_area_high approximate the high-volume range around POC.
  • DerivedAnalyticsSnapshot adds session totals such as total_volume, trade_count, vwap, average_trade_size, and imbalance_bps without changing the original analytics payload.
  • SessionCandleSnapshot adds a candle-style session view with open, high, low, close, trade_count, and first/last exchange timestamps.
  • IntervalCandleSnapshot adds a parameterized rolling-window candle view with window_ns, open, high, low, close, trade_count, total_volume, vwap, and first/last exchange timestamps.

For full orchestration and adapter integration, see of_runtime.

§Book Snapshot Model

BookSnapshot materializes the latest known order book for one symbol:

  • bids: bid-side levels ordered by level
  • asks: ask-side levels ordered by level
  • last_sequence: sequence number of the most recent applied book event
  • ts_exchange_ns / ts_recv_ns: timestamps from the most recent applied book event

This snapshot model is used by the runtime and exposed through the FFI and bindings.

§Choosing the Right Snapshot Type

§Real-World Use Cases

§1. Offline research and replay analytics

Use AnalyticsAccumulator directly when you already have normalized trade data and want deterministic session analytics without the full runtime.

Typical use cases:

  • replaying one session from a CSV/JSONL converter
  • validating a strategy hypothesis before wiring live adapters
  • generating session summaries for dashboards or reports

§2. Shared schema between components

Use of_core as the common contract when writing:

  • custom adapters that emit normalized BookUpdate and TradePrint
  • custom signal modules that consume AnalyticsSnapshot
  • persistence or replay tools that must stay aligned with runtime semantics

§3. Strategy prototyping before runtime integration

For early-stage ideas, it is often faster to work only with TradePrint, AnalyticsAccumulator, and the output snapshot types before integrating with of_runtime.

§Detailed Example: Build Session Analytics From Trades

use of_core::{AnalyticsAccumulator, Side, SymbolId, TradePrint};

fn main() {
    let symbol = SymbolId {
        venue: "CME".to_string(),
        symbol: "ESM6".to_string(),
    };

    let trades = vec![
        TradePrint {
            symbol: symbol.clone(),
            price: 505_000,
            size: 8,
            aggressor_side: Side::Ask,
            sequence: 1,
            ts_exchange_ns: 1_000,
            ts_recv_ns: 1_100,
        },
        TradePrint {
            symbol: symbol.clone(),
            price: 505_025,
            size: 4,
            aggressor_side: Side::Ask,
            sequence: 2,
            ts_exchange_ns: 2_000,
            ts_recv_ns: 2_100,
        },
        TradePrint {
            symbol,
            price: 505_000,
            size: 6,
            aggressor_side: Side::Bid,
            sequence: 3,
            ts_exchange_ns: 3_000,
            ts_recv_ns: 3_100,
        },
    ];

    let mut acc = AnalyticsAccumulator::default();
    for trade in &trades {
        acc.on_trade(trade);
    }

    let analytics = acc.snapshot();
    let derived = acc.derived_snapshot();
    let session_candle = acc.session_candle_snapshot();
    let interval_candle = acc.interval_candle_snapshot(5_000);

    println!(
        "delta={} poc={} total_volume={} vwap={:.2}",
        analytics.delta,
        analytics.point_of_control,
        derived.total_volume,
        derived.vwap
    );
    println!(
        "session ohlc=({}, {}, {}, {}) trades={}",
        session_candle.open,
        session_candle.high,
        session_candle.low,
        session_candle.close,
        session_candle.trade_count
    );
    println!(
        "interval close={} interval_vwap={:.2}",
        interval_candle.close,
        interval_candle.vwap
    );
}

§Strategy-Prototyping Pattern

A common progression is:

  1. use TradePrint and AnalyticsAccumulator to compute deterministic features
  2. test threshold logic over AnalyticsSnapshot and DerivedAnalyticsSnapshot
  3. once stable, move the logic into an of_signals::SignalModule
  4. finally run it inside of_runtime for live or replay orchestration

Structs§

ACDModel
Tracks trade durations and estimates ACD(1,1).
ACDSnapshot
ACD(1,1) model for trade duration.
AgentTypeDetector
Infers agent types from trade and book patterns.
AgentTypeSnapshot
Agent-type identification snapshot.
AlertRule
Configurable real-time alert switches.
AlmgrenChriss
Tracks volume and price changes for impact estimation.
AlmgrenChrissSnapshot
Almgren-Chriss market impact model.
AmihudSnapshot
Snapshot of Amihud illiquidity.
AmihudTracker
Tracks Amihud Illiquidity: |return| / dollar_volume per bar.
AnalyticsAccumulator
In-memory accumulator that updates analytics state from normalized trades.
AnalyticsConfig
Configurable analytics thresholds and buffer sizes. All fields have sensible defaults suitable for typical US equity/crypto markets. Pass an instance to the runtime engine config setter or the C ABI setter to override.
AnalyticsSnapshot
Aggregated analytics for a symbol/session.
BookAnalyticsSnapshot
Snapshot of book-derived analytics computed from an order book snapshot.
BookEventAnalyticsSnapshot
A snapshot of book-event analytics.
BookEventSample
A single book update event for analytics.
BookEventTracker
Tracks order-book update events for rate and size-distribution analytics.
BookLevel
One normalized price level in a materialized book snapshot.
BookSnapshot
Materialized order-book snapshot for a symbol.
BookUpdate
Level-2 order book update.
ClassifierWeights
Weights for the consensus voting classifier.
CompletedBar
A completed fixed-interval OHLCV bar.
CryptoSnapshot
Snapshot of crypto-market flow analytics.
CvdEnhancementSnapshot
Snapshot of CVD enhancement metrics.
CvdEnhancements
Tracks CVD (Cumulative Volume Delta) enhancements: ratio, z-score, divergence.
DarkLitCorrelationSnapshot
Snapshot of dark-lit imbalance correlation.
DarkLitCorrelator
Tracks rolling dark-lit imbalance correlation.
DarkPoolSnapshot
Dark pool analytics snapshot.
DarkPoolTracker
Tracks dark pool volume alongside lit volume.
DataQualityFlags
Bitset wrapper for feed-quality flags.
DerivedAnalyticsSnapshot
Additive derived analytics computed from the current session accumulator state.
FXSnapshot
Snapshot of FX-specific flow analytics.
FixedIncomeSnapshot
Snapshot of fixed-income flow analytics.
FuturesSnapshot
Futures analytics snapshot.
FuturesTracker
Tracker for futures contract roll and basis.
HasbrouckSnapshot
Hasbrouck bivariate VAR(1) for price impact decomposition.
HasbrouckVAR
Tracks returns and signed volume for Hasbrouck VAR.
InstitutionalFlowSnapshot
Snapshot of institutional-flow classification.
InstitutionalFlowTracker
Tracks large trades for institutional-flow classification.
IntervalCandleSnapshot
Rolling interval candle-style summary derived from recent session trades.
KineticEnergySnapshot
Kinetic energy of order book activity.
KineticEnergyTracker
Tracks book changes to compute kinetic energy analogues.
KyleLambdaSnapshot
Snapshot of Kyle’s Lambda estimation.
KyleLambdaTracker
Tracks Kyle’s Lambda: ΔP = α + λ * signed_volume + ε over a rolling window.
LOBFeatureSnapshot
40+ hand-crafted LOB features for ML models.
MicrostructureNoise
Tracks price returns for noise estimation.
NoiseSnapshot
Microstructure noise estimate and signal-to-noise ratio.
OIAnalysisSnapshot
Snapshot of open-interest analysis.
OIAnalyzer
Tracks open interest and price for divergence analysis.
OptionsFlowSnapshot
Options flow snapshot.
OptionsFlowTracker
Tracks options trade flow.
PatternDetector
Detects practitioner orderflow patterns from book and trade data.
PatternSnapshot
All detected practitioner patterns in one snapshot. Snapshot of all detected practitioner patterns.
RegimeDetector
Classifies market regime from spread, volatility, and VPIN.
RegimeSnapshot
Snapshot of market-regime classification metrics.
ResiliencySample
Book depth around a single trade.
ResiliencySnapshot
A snapshot of book resiliency metrics for the most recent trade.
ResiliencyTracker
Tracks book depth before and after trades for resiliency metrics.
SessionCandleSnapshot
Session candle-style summary derived from the current analytics session.
SignalSnapshot
Snapshot of a signal module evaluation.
SpreadDecomposition
Tracks spreads for Huang-Stoll decomposition.
SpreadDecompositionSnapshot
Huang-Stoll spread decomposition.
SpreadSample
One recorded trade for spread tracking.
SpreadTracker
Tracks effective and realised spread for recent trades.
SymbolId
Canonical market symbol identifier used across venues.
TradeClassifier
Classifies trades using multiple methods: tick rule, quote rule, Lee-Ready, and consensus.
TradePrint
Last-trade print/tick.
VolatilityEstimator
Tracks OHLC prices per bar for volatility estimation.
VolatilitySignature
Computes volatility signature from return series.
VolatilitySignaturePoint
Volatility signature result at a specific lag.
VolatilitySignatureSnapshot
Volatility signature plot: RV at multiple lags.
VolatilitySnapshot
Realised volatility estimators: Classic, Parkinson, Garman-Klass, Yang-Zhang.
VpinSnapshot
A single VPIN snapshot.
VpinTracker
Tracks Volume-Synchronized Probability of Informed Trading (VPIN).

Enums§

BookAction
Book mutation kind.
ClassificationVote
Result of a single trade classification method.
Regime
Market regime classification.
Side
Trade or book side.
SignalState
Output state emitted by signal modules.

Traits§

StateCheckpoint
Trait for state serialization.

Functions§

compute_book_analytics
Computes book-derived analytics from a materialized order book snapshot.
compute_depth_slope
Computes the depth slope — average volume decay per level away from the top of book.
compute_effective_spread_bps
Computes effective spread in basis points for a single trade.
compute_lob_features
Computes LOB features from book snapshot and trade flow.
compute_mid_price
Returns the mid price from a book snapshot, or None if either side is empty.
compute_realised_spread_bps
Computes realised spread in basis points.
compute_weighted_average_price
Computes the weighted average price for an order of qty shares walking the book.