sequence-algo-sdk 0.4.0

//! Trading algorithm traits.
//!
//! Two usage patterns:
//! - `Algo` — single-venue algo, sees local book, trades on local OMS.
//!   Use `export_algo!()` macro.
//! - `Algo` with mesh messaging — deploy to multiple venues, communicate
//!   via `send()`/`on_message()`. Use `export_algo!()` macro (same macro, runtime auto-detects).

use crate::{Actions, AlgoState, Fill, L2Book, NbboSnapshot, OnlineFeatures, Reject, VenueBooks};

// =============================================================================
// ALGO TRAIT
// =============================================================================

/// Trading algorithm trait.
///
/// **Single-venue**: implement `on_book` only. Use `export_algo!()`.
///
/// **Mesh (multi-venue)**: also implement `on_message` and optionally
/// `on_nbbo`. Use `export_algo!()`. Call `send()` from any callback
/// to message other mesh participants. Runtime auto-detects mesh capabilities.
///
/// All methods run on HOT PATH — avoid heap allocations.
pub trait Algo: Send {
    /// Called on every local book update.
    fn on_book(
        &mut self,
        book: &L2Book,
        state: &AlgoState,
        features: &OnlineFeatures,
        actions: &mut Actions,
    );

    /// Order filled. Default: no-op.
    fn on_fill(&mut self, _fill: &Fill, _state: &AlgoState) {}

    /// Order rejected. Default: no-op.
    fn on_reject(&mut self, _reject: &Reject) {}

    /// Shutdown — cancel open orders here. Default: no-op.
    fn on_shutdown(&mut self, _state: &AlgoState, _actions: &mut Actions) {}

    /// Heartbeat callback (1 Hz, optional). Default: no-op.
    fn on_heartbeat(
        &mut self,
        _state: &AlgoState,
        _features: &OnlineFeatures,
        _actions: &mut Actions,
    ) {
    }

    /// Message received from another mesh algo instance.
    ///
    /// `from`: sender's label (e.g., "maker", "hedger") — matches what they set in Sequence.toml.
    /// `payload`: opaque bytes (max 256). Define your own format.
    ///
    /// Use `messaging::send(label, payload)` to reply.
    fn on_message(
        &mut self,
        _from: &str,
        _payload: &[u8],
        _state: &AlgoState,
        _actions: &mut Actions,
    ) {
    }

    /// Called on NBBO update (multi-venue visibility). Default: no-op.
    ///
    /// Only fires if the WASM module exports `algo_on_nbbo` (via `export_algo!`).
    /// CC pushes aggregated NBBO from all venues to hosting edges.
    fn on_nbbo(
        &mut self,
        _nbbo: &NbboSnapshot,
        _books: &VenueBooks,
        _state: &AlgoState,
        _features: &OnlineFeatures,
        _actions: &mut Actions,
    ) {
    }
}