Crate hypercall_engine 

Pure deterministic engine state machine for the Hypercall options exchange.

hypercall-engine is the financial core of the Hypercall matching engine, extracted into a standalone crate with zero runtime dependencies. It contains position tracking, MMP (Market Maker Protection) state, and the command/event types that define the engine’s public interface.

Design Constraints

This crate is deliberately minimal. It has:

• No async runtime. Every method is synchronous. No tokio, no futures.
• No database. Persistence is the runtime’s job, routed through traits::JournalWriter.
• No networking. Event distribution goes through traits::EventSink.
• No filesystem access. The engine never touches std::fs.
• No unsafe code.

These constraints exist so that the engine is fully deterministic: given the same sequence of commands, it always produces the same state and events. This property enables crash recovery via journal replay, state replication to standby instances, and independent validator verification.

Architecture

All state transitions follow a pure function pattern:

Commands IN  -->  apply(state, cmd) --> (new_state, events)

External data (spot prices, IV surfaces, deposits, orders) enters as EngineCommand variants. The engine processes each command synchronously and produces an ApplyOutput containing the resulting events and a state hash for replication.

The outer hypercall crate provides the runtime (tokio, channels, WAL persistence) and implements the traits defined in traits.

Modules

• command – Input commands (EngineCommand) and output (ApplyOutput).
• position – Position tracking with fill application, weighted-average entry price, and realized PnL calculation (EnginePosition).
• mmp – Market Maker Protection state machine with configurable rolling windows, greek limits (quantity, delta, vega), and timed freeze (EngineMmpState).
• traits – Trait boundary between engine and runtime: traits::EventSink, traits::JournalWriter, traits::CommandPublisher.
• proofs (cfg-gated, #[cfg(kani)]) – Kani bounded model checking harnesses that verify conservation of value, PnL sign consistency, MMP correctness, and zero-sum matching. Run with cargo kani -p hypercall-engine.

Trait Boundary

The runtime implements three traits to wire the engine into production:

• traits::EventSink – Routes engine events to WebSocket clients, persistence, and downstream caches.
• traits::JournalWriter – Writes commands to a WAL for crash recovery.
• traits::CommandPublisher – Replicates commands to standby instances.

In tests, these traits can be stubbed with in-memory implementations.

Standalone / Validator Usage

Because the engine is a pure state machine, external validators can import this crate, replay the command stream, and compare state hashes:

use hypercall_engine::{EngineCommand, ApplyOutput};

// For each command from the sequencer's stream:
let output: ApplyOutput = engine.apply(command);
assert_eq!(output.hash, sequencer_published_hash);

Hash divergence constitutes proof of sequencer misbehavior.

Re-exports

pub use accounting::apply_fill_accounting;

pub use accounting::apply_fill_position_accounting;

pub use accounting::calculate_fill_accounting;

pub use accounting::fill_premium_delta;

pub use accounting::FillAccountingContext;

pub use accounting::FillAccountingPosition;

pub use accounting::FillCashSettlement;

pub use admission::OrderAdmissionDecision;

pub use admission::OrderAdmissionInput;

pub use admission::OrderAdmissionState;

pub use command::ApplyOutput;

pub use command::EngineCommand;

pub use fee::FeeCalculation;

pub use fee::FeeConfig;

pub use fee::FeeService;

pub use instrument::contract_key;

pub use instrument::is_option_symbol;

pub use instrument::perp_underlying;

pub use instrument::ParsedInstrument;

pub use margin_admission::decide_portfolio_margin;

pub use margin_admission::decide_standard_margin;

pub use margin_admission::margin_decision_result;

pub use margin_admission::MarginAdmissionDecision;

pub use margin_admission::PortfolioMarginAdmissionInput;

pub use margin_admission::StandardMarginAdmissionInput;

pub use matching::MmpTriggerIntent;

pub use matching::OptionMatchOutcome;

pub use mmp::EngineMmpState;

pub use mmp::MmpFillRecord;

pub use nonce::nonce_within_time_bounds;

pub use nonce::BoundedNonceSet;

pub use order_index::EngineOrderIndex;

pub use order_index::OpenSellPositionInfo;

pub use order_index::OrderSummary;

pub use orderbook::L2UpdateSet;

pub use orderbook::MatchResult;

pub use orderbook::Order;

pub use orderbook::OrderBook;

pub use orderbook::OrderBookEvent;

pub use orderbook::OrderRecord;

pub use position::EnginePosition;

pub use position::PositionFillTransition;

Modules

accounting

admission

Pure order admission checks.

command

Engine command and output types.

fee

Fee calculation service for trading fees.

greeks

Pure greek calculations used by engine admission and MMP checks.

instrument

Pure instrument parsing helpers for engine-owned validation.

margin_admission

Pure margin-admission decisions.

matching

Pure matching result types shared by the runtime adapter.

mmp

Engine-internal MMP (Market Maker Protection) state.

nonce

order_index

In-process order index for the engine.

orderbook

Pure orderbook data structure and matching engine.

position

Engine-owned position tracking.

traits

Trait boundary between engine-core and the runtime.

Structs

FillAccounting